Twinmotion MCP

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

With no annotations provided, the description carries full burden and excels. It discloses side effects (starts translation job, consumes APS credits, writes usage_log, not idempotent), error codes with meanings, rate limits, and performance expectations (multi-GB, 10-45 min). It also clarifies it does not itself produce video, preventing false expectations.

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 extremely well-structured with sections (what, when to use, when not, scopes, rate limits, errors, side effects). Each sentence delivers critical information without redundancy. It is front-loaded with the core purpose and then logically expands into usage guidance, making every sentence earn 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?

Given the tool's complexity (starts background job, has prerequisites, multiple error modes), the description is comprehensive. It covers prerequisites (manifest status, model fully translated), explains output (list of named views, status='pending' short-circuit), and lacks an output schema but still communicates return behavior. The error taxonomy and side-effect disclosure make it fully contextual for an 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 each parameter already having a clear description (e.g., format enum meanings, project_id URN requirements). The tool description adds no additional parameter-specific semantics beyond what the schema provides; it merely echoes some naming suggestions already present in the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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 'prepares a model for animated walkthrough/video export' by verifying the manifest and starting a Model Derivative job to produce OBJ geometry. It explicitly distinguishes itself from actual video encoding by stating 'Does NOT itself produce an mp4', and differentiates from siblings by mentioning 'not for still images (use tm_render_image)' and 'clash animations (use navisworks-mcp)'.

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 dedicated 'When to use' and 'When NOT to use' sections. It specifies using it for walkthrough/flythrough video requests, and explicitly lists exclusions: not for actual encoding, not before tm_import_rvt, not if manifest is 'inprogress', and not for still images or clash animations. It even names alternative tools, providing excellent decision support.

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

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

No annotations are provided, so the description carries full burden. It discloses side effects (creates transient bucket, starts translation job, consumes credits, not idempotent), rate limits, polling/backoff strategy, required APS scopes, and detailed error-code mappings. This is far beyond minimal 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?

Though long, the description is front-loaded with a clear summary sentence and then organized into labeled sections (When to use, When NOT to use, APS scopes, Rate limits, Errors, Side effects). Every sentence adds necessary context, and the structure makes it easy for an agent to scan. Appropriate length for the tool's 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 explicitly states what is returned (base64 URN/project_id). It comprehensively covers prerequisites, side effects, error handling, rate limits, and parameter roles. Given the absence of annotations and output schema, this is exceptionally 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%, so baseline is 3. The description adds extra constraints not in the schema, such as the ~100MB worker ceiling and advisory for signed-URL upload on large files. This provides meaningful supplement to file_url semantics, warranting a 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 states a specific verb+resource: 'Import a Revit/BIM model into the Twinmotion visualization pipeline' and details the full workflow (download, upload, translate). It clearly distinguishes from siblings by positioning this as the first step before rendering/scene-definition/export, and explicitly names alternatives like navisworks-mcp and qto-mcp.

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 ('when a user wants to prepare a Revit/IFC/BIM model... typically the first step') and when-not-to-use ('not for MEP clash review... use navisworks-mcp') with alternative tools named. This gives an AI agent unambiguous selection criteria.

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

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

With no annotations provided, the description carries the full burden and excels: it discloses read-only status across APS endpoints, required APS scopes (viewables:read data:read), rate limits (~50 req/min) with fan-out caveat for 10+ views, a full error-code map including 429 backoff and internal retry on 202, and side effects (writes usage_log row, idempotent, no APS mutation).

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 organized into labeled sections with front-loaded main purpose. While long, every sentence earns its place: rate limits, error details, side effects, and alternatives are all operational necessities. This is deliberate structure, not verbosity.

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 no output schema and no annotations, the description fully covers return content, error handling, rate limits, side effects, prerequisites, and alternatives. It is complete enough for an agent to invoke without missing critical constraints.

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?

Input schema covers the single parameter 100% with base64 URL-safe URN description and status caveat. The tool description adds no additional parameter semantics beyond this, so baseline 3 is appropriate.

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 opens with specific verb 'Enumerate' and concrete outputs: every 2D/3D view, shallow object-tree dump (first 50 top-level nodes), and completed derivatives list. It explicitly names itself 'canonical discovery tool' for view names/GUIDs, clearly distinguishing it from render/export/import siblings.

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?

Contains explicit 'When to use' and 'When NOT to use' sections, naming alternative tools (property-query tool, tm_export_video for OBJ) and listing prerequisite conditions (not on a URN that hasn't started translating). This is textbook usage guidance.

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

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

With no annotations, the description carries the full burden and excels: discloses APS scopes, rate limits (50 req/min, no loop-polling), error semantics for 401/403/404/429/5xx, and side effects (read-only, writes usage_log, idempotent). 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 structured with clear sections and every sentence adds value—usage directives, scopes, rate limits, errors, side effects. It is appropriately detailed for a tool that touches APS endpoints, without fluff.

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?

The description covers usage, exclusions, auth scopes, rate limits, error codes, side effects, and prerequisites, but does not explicitly specify the return format (e.g., URL vs base64) since there is no output schema. This is a minor gap for an agent that needs to consume the result.

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 has 100% description coverage, but the description adds meaning beyond schema: explains resolution clamping to 800x800, camera_preset fallback to first 3D view, and quality as metadata only. It also points to tm_list_scenes for valid values.

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 opens with a specific verb and resource: 'Render a still preview image... by pulling the APS Model Derivative thumbnail.' It clearly distinguishes from sibling tools by explicitly excluding production renders (use UE Movie Render Queue) and 2D sheet exports (use tm_list_scenes).

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?

Includes dedicated 'When to use' and 'When NOT to use' sections with explicit alternatives like UE Movie Render Queue for cinematic output and tm_list_scenes for 2D sheets. Also recommends pairing with tm_list_scenes to discover valid view names.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses the KV write side effect with TTL, idempotency, usage_log write, required APS scopes, rate limits, error code meanings, and the validation-before-write behavior. It also clarifies that APS permissions are read-only despite the KV side effect, preventing false assumptions.

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 tightly structured with labeled sections (when to use, when not, scopes, rate limits, errors, side effects). Every sentence provides actionable information; there is no filler or redundancy. The front-loaded purpose sentence immediately establishes the tool's essence, and the rest expands with necessary operational details.

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 no annotations and no output schema, the description is impressively complete. It covers prerequisites, usage flow, authentication requirements, error handling, rate limits, side effects, and idempotency. An agent has everything needed to decide when and how to call this tool, and what to expect afterward.

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?

Input schema coverage is 100% and each parameter already has a descriptive explanation, enum values, and examples. The description adds context about how parameters collectively feed the scene config but does not materially go beyond the schema's per-parameter semantics. Baseline 3 is appropriate since the schema handles parameter documentation.

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 opens with a specific verb+resource+scope: 'Configure the visualization environment (weather, time-of-day, surround context) for a previously imported model.' It clearly differentiates from siblings by stating the config is stored for tm_render_image and tm_export_video to apply, and identifies its role as step 2 in the Twinmotion flow.

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 explicitly states when to use it (after tm_import_rvt completes, optionally pre-staging config even if manifest is in-progress) and when NOT to use it (editing geometry/materials/UE post-process volumes, or before import). It names sibling tools as the intended consumers and gives a concrete user-intent example, leaving 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.