ScanBIM MCP

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

With no annotations provided, the description fully discloses behavioral traits: non-idempotency (creates duplicates on repeated calls), side effects (inserts into D1 usage_log), error conditions (401/403/404/429/5xx) with actionable advice, and required APS scopes. It also notes that linked_model_id is not forwarded to ACC's linkedDocuments field. This goes beyond the schema and is exceptionally transparent for a mutating tool.

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 (When to use, When NOT to use, APS scopes, Rate limits, Errors, Side effects) and front-loads the main purpose. It is verbose, but most content is relevant. The rate limits section includes Model Derivative and OSS details that are not directly relevant to this Issues API, adding minor noise. Still, it is organized and readable, so a 4 is appropriate.

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 has 7 parameters, no annotations, no output schema, and is a mutation with side effects, the description covers all necessary context: purpose, usage triggers, exclusions, scopes, rate limits, error handling, side effects, and return value. It is comprehensive enough for an agent to know when and how to invoke it correctly, and what to expect in response.

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 the schema already documents all parameters well. The description adds extra semantic value by explaining that the worker strips the 'b.' prefix from project_id (also in schema), and clarifies that linked_model_id is only for ScanBIM cross-referencing and not sent to ACC. These details are not obvious from the schema alone, justifying an above-baseline score of 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 the tool creates an ACC issue via the APS Construction Issues v1 API, specifying the exact resource (Issues module) and action (create). It distinguishes itself from siblings by explicitly naming acc_create_rfi as the alternative for RFIs and clarifying that markups are not issues. This is a specific verb+resource pair with clear differentiation.

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. It gives concrete triggers (detect_clashes flagged a critical clash, field user reports a QC defect) and excludes alternatives (acc_create_rfi, model markups). It also provides error handling guidance and rate limit context, making it clear when to invoke this tool versus alternatives.

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 fully carries the burden of behavioral disclosure. It details side effects (non-idempotent, creates a draft each call, inserts usage log), error codes and handling, rate limits, and required scopes. This goes well beyond what annotations would typically provide.

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, scopes, rate limits, errors, side effects). Every sentence adds value, and the most important facts are front-loaded. Despite its length, it remains tight and scannable.

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 mutation tool with no annotations and no output schema, the description covers all critical context: prerequisite scopes, common error responses and remedies, rate limits, non-idempotency, and side effects. It even mentions the return value (rfi_id) and the D1 usage log, making it complete for an agent 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific semantics beyond what the schema already provides (e.g., project_id format, assigned_to nullability). The schema itself is thorough with examples and edge-case notes, so no deduction is needed, but no extra credit is earned.

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's function: creating an RFI in draft status via the APS RFIs API, and explicitly distinguishes it from the sibling tool acc_create_issue by specifying when to use it. The verb 'Create' plus the resource 'Request For Information' and module 'ACC Build's RFIs' make the purpose unambiguous.

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' and 'When NOT to use' sections with concrete scenarios and names the alternative tool (acc_create_issue) for punchlist fixes. This gives an AI agent clear decision criteria for selecting this tool over siblings.

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 delivers: READ-ONLY, idempotent, side effect of inserting into D1 usage_log, error codes with remediation, rate limits, and APS scopes. It also discloses that 'assigned_to' is currently not forwarded to the API. This is exemplary 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?

The description is well-structured with clear sections and front-loaded purpose, but includes extraneous details like Model Derivative and OSS upload rate limits that are not relevant to listing issues. While useful for the broader APS context, these noise elements prevent a perfect score.

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 read-only list tool with a rich schema and no output schema, the description is complete: it explains the return shape, the 50-item cap, the 'assigned_to' caveat, error handling, and usage contexts. No critical information is missing for an agent to select and invoke this tool 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?

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-level detail beyond what the schema already provides; it repeats the status/priority filters but does not explain accepted values or formats beyond the schema. The schema, however, fully documents all four parameters, so no deduction is necessary.

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 a specific verb ('List'), resource ('issues'), and scope ('up to 50 issues from an ACC project'), and clearly differentiates this from sibling tools like acc_create_issue and acc_list_rfis. It also states the return format ('normalized array of {id, title, status, priority, due_date}').

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 provide clear guidance, including the key limitation (caps at 50 results, no pagination) and an alternative (per-issue endpoint or ACC Issues UI). This fully addresses when to use this tool vs. alternatives.

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 full burden and excels: discloses READ-ONLY nature, idempotency, side effect of inserting into D1 usage_log, required APS scopes, rate limits, and detailed error codes with recovery actions. This goes far beyond a typical tool description.

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 into clear labeled sections (purpose, when to use, when not, scopes, rate limits, errors, side effects). Every sentence provides actionable information; no fluff. It is front-loaded with the core purpose and immediately usable guidance.

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 covers all essential context: use cases, exclusions, scopes, rate limits, errors, side effects, and output fields. The error handling and recovery suggestions are particularly valuable. This is a complete standalone reference 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?

The tool accepts zero parameters, and the input schema confirms this with 100% coverage. The description adds context by listing the output fields and the flattened-across-hubs behavior, but since there are no parameters, the baseline of 4 applies. No additional parameter semantics are needed.

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 uses a specific verb ('List') and clearly defines the resource ('every ACC/BIM 360 project') and output fields (hub_id, hub_name, etc.). It distinguishes itself from sibling tools by stating it is the tool to use when you need a project_id for other ACC tools, and explicitly notes the N+1 API calls behavior that differentiates it from alternatives.

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' and 'When NOT to use' sections, citing specific sibling tools for both scenarios. It also warns about performance implications ('N+1 API calls... avoid calling it in tight loops'), giving clear alternative 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 fully discloses behaviors: 'Side effects: READ-ONLY. Inserts a row into D1 usage_log. Idempotent.' It also lists APS scopes, rate limits, and detailed error handling. It states the return shape and limits, leaving little hidden behavior.

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 a clear opening purpose, then usage, then technical details in labeled sections. While longer than some, every sentence serves a purpose—scopes, errors, side effects—and it is front-loaded with the primary action.

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?

Although there is no output schema, the description gives the return array shape: '{id, subject, status}'. It also covers error handling, rate limits, side effects, and limits (50 max, no pagination), making it fully contextual for a list operation.

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 the schema already describes both parameters with examples and prefix-stripping behavior. The description itself adds no parameter-specific detail beyond the initial mention of status filtering, so the baseline of 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?

The description opens with a specific verb and resource: 'List up to 50 RFIs from an ACC project, optionally filtered by status.' This clearly distinguishes it from sibling tools like acc_create_rfi and acc_list_issues, and clarifies scope by stating it does not include full response threads.

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 provide clear guidance, including an alternative: 'use the ACC UI or per-RFI endpoint.' It also notes the 50-result cap and lack of pagination, helping an agent decide if this tool fits the task.

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 fully discloses behavior: READ-ONLY, idempotent, writes to D1 usage_log, plus APS scopes, rate limits, and detailed error handling by HTTP code. This goes beyond typical descriptions and completely covers the safety and side-effect profile.

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 front-loaded with the main purpose, followed by clear usage guidance, and then supporting details (scopes, limits, errors, side effects). Each sentence serves a distinct function, and the use of headers and bullets makes it easy to scan.

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 single-project fetch tool with no output schema, the description covers purpose, when to use/avoid, parameter semantics (via schema), side effects, error handling, and rate limits. The implied return attributes (name, type, dates, address, hub) are explicitly listed, making the tool fully comprehensible.

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 already provides 100% coverage of both parameters, including the default behavior for omitted hub_id and the requirement to pass project_id unchanged. The description adds little beyond restating these facts, so the baseline score of 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?

The description uses a specific verb ('Fetch') and resource ('single ACC/BIM 360 project's full attributes') and explicitly names the APS Data Management project endpoint. It differentiates from siblings by specifying 'single project' and naming alternative tools for list operations.

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 acc_list_projects for listing projects and the list tools for issues/RFIs counts. This provides clear decision guidance for selecting between alternatives.

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 behavioral burden. It discloses read-only operation, side effects (D1 usage_log row insertion), idempotency, APS scopes (data:read, account:read), rate limits, and detailed error handling (401/403/404/429/5xx) including the 'b.' prefix behavior. This goes far beyond what structured fields would provide.

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, when not to use, scopes, rate limits, errors, and side effects. Information is front-loaded and most sentences earn their place. However, the rate limit section includes unrelated details about Model Derivative and OSS uploads, which adds noise and reduces conciseness.

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 compensates comprehensively. It covers what the tool does, its boundaries, error handling, scopes, side effects, and even notes that it returns metadata. This is a complete picture for an agent to decide when to use and what to expect.

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 well-written descriptions and examples for all parameters. The description does add minor context (e.g., project_id 'b.' prefix handling, URL encoding), but the schema already covers these details. Thus the baseline of 3 is appropriate; the description adds little 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 opens with a clear, specific action: 'Full-text search the ACC Docs module on a project for drawings, specs, submittals, and other documents matching a query string.' It names the resource (ACC Docs module), the endpoint, and the scope (project-level), making it easy to distinguish from sibling tools like acc_list_issues or acc_list_projects.

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 provide concrete scenarios and exclusions. The description gives keyword examples ('fireproofing', 'A-101') and explicitly tells agents to fetch directly if they already have a URN, and to use Data Management for file contents. This clearly differentiates from alternatives.

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?

Despite having no annotations, the description discloses the algorithm (AABB bounding-box intersection), fallback behavior, APS scopes, rate limits, error responses, read-only side effect on APS, usage_log insertion, and idempotency. It fully carries the transparency burden.

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 and front-loaded purpose. It loses a point because the rate-limit paragraph includes unrelated OSS upload size details that don't apply to this tool, adding noise to an otherwise efficient definition.

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 explains return contents (overlapping pairs, severity, suggested fix, rework hours), preconditions (translation status), side effects, error handling, and idempotency. For a complex 3-parameter tool with no annotations, this is fully 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?

Input schema coverage is 100%, and parameter descriptions already explain model_id, category_a, and category_b with examples and case-sensitivity notes. The description adds only general context about MEP/structural trades, not parameter-level detail beyond the schema, so the 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 a specific verb phrase: 'Run a VDC-grade clash detection pass between two element categories in a translated model, returning each overlapping element pair with severity, suggested fix, and rework hours.' This clearly distinguishes it from sibling tools like get_model_metadata or lumion_render and defines the primary resource and action.

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 tell the agent to call get_model_metadata first if translation hasn't completed and to invoke the tool multiple times for more than two categories. This is directly actionable guidance with an alternative/reference tool named.

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 full burden and delivers: it states READ-ONLY, idempotency, inserts a usage_log row, lists APS scopes, rate limits, and error codes with handling hints. No annotation contradiction.

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 lengthy, the description is tightly organized with labeled sections (When to use, When NOT to use, APS scopes, Rate limits, Errors, Side effects). Every sentence delivers actionable information; no filler or redundancy.

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 fully equips the agent: clear purpose, usage context, alternatives, scopes, error handling, side effects, and rate limits. It even notes what the tool does not return (full properties). This is a model of completeness.

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 single parameter model_id is fully described in the schema with type, example, and source (returned by upload_model). The description adds no additional parameter semantics, but schema coverage is 100%, so the baseline of 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?

The description opens with a specific verb and resource: 'Fetch the APS Model Derivative manifest and metadata for a URN.' It lists concrete return contents (translation progress, derivative outputs, viewer URL) and implicitly distinguishes from siblings like get_viewer_link by stating what it does NOT do.

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' (poll translation after upload_model, inspect derivatives) and 'When NOT to use' sections with named alternatives (get_viewer_link, property collection). This is the gold standard for 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 discloses that the tool is READ-ONLY, pure, idempotent, and requires no APS scope. It also clarifies that many errors are not applicable. However, the rate-limit section includes irrelevant info about Model Derivative and OSS uploads, slightly detracting from clarity.

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 headers, but there is redundancy between the introductory sentence and the 'When to use' section. The rate and error details are verbose and partially irrelevant, making it not as concise as it could be.

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 lacking an output schema, the description specifies the return value ('full matrix of supported input formats'), use cases, exclusions, safety profile, and error behavior. No further information is needed 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?

There are zero parameters, so the description has no parameter semantics to add. The schema is empty and fully covers parameters, so the baseline 4 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 first sentence clearly defines the tool: 'Return the full matrix of supported input formats organized by subscription tier.' It specifies a concrete verb and resource, and distinguishes itself from siblings by explicitly tying to upload_model use cases.

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 upload_model as the alternative when the extension is common. This is exactly the guidance needed for tool selection.

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 does so thoroughly. It discloses that the model need not be fully translated (viewer polls manifest), that the tool itself requires no APS scopes but the viewer page uses viewables:read/data:read via /token, rate limits, error codes, and that the operation is read-only, pure, and idempotent. This adds rich behavioral context beyond the basic function.

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?

Although longer than typical, the description is highly structured with labeled sections: purpose, when to use, when not to use, scopes, rate limits, errors, side effects. Every sentence adds factual value, and the most important information is front-loaded. No redundancy or filler.

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?

This is a single-parameter, no-output-schema tool, yet the description covers all relevant context: operational behavior (polling manifest), safety profile (read-only, idempotent), constraints (rate limits, errors), and alternatives. It is complete enough for an agent to confidently decide when and how to invoke the 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 description coverage is 100%; the param model_id already has a detailed explanation including format and examples. The description adds a small amount of extra meaning by linking model_id to upload_model and noting idempotence, but this does not significantly improve on the schema's explanation. 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?

The description clearly states the tool 'Return a shareable browser URL for the embedded APS viewer and a matching QR code for mobile/XR handoff.' This is a specific verb+resource combination. It also distinguishes itself from siblings by explicitly saying 'Do not use to check translation progress — call get_model_metadata' and 'you need the raw APS URN for programmatic API calls — use the model_id you already have instead.'

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 gives explicit 'When to use' (hand a stakeholder a URL or print a QR) and 'When NOT to use' (for raw URN or translation progress), naming alternative tools (get_model_metadata). This is exactly the kind of decision guidance the dimension asks for.

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 full burden and excels: it discloses read-only and idempotent behavior, pagination limits, scopes, rate limits, and detailed error semantics. This goes far beyond what structured annotations would typically provide.

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?

While lengthy, every section earns its place: purpose, when-to-use, exclusions, scopes, rate limits, errors, and side effects. The structure is front-loaded with a crisp first sentence and organized with clear paragraph breaks, maximizing information density without waste.

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 simplicity (no output schema, minimal params), the description is fully complete for an agent: it covers pagination, error handling, auth scopes, and the relationship to other tools. No critical operational context is missing.

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 already documents both parameters with 100% coverage, including the crucial note that they are 'informational only' and do not filter results. The description itself adds no parameter-level meaning, so baseline 3 is appropriate; the schema handles semantic burden adequately.

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 'List every object currently stored in the scanbim-models OSS bucket' with specific output fields (URN, size, viewer URL). It explicitly contrasts with the D1 models table and distinguishes itself from sibling get_model_metadata, making the tool's unique purpose unambiguous.

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' and 'When NOT to use' sections, naming a concrete alternative (get_model_metadata) and clarifying that it is not a search and returns paginated results. This is exemplary guidance for tool selection.

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 of behavioral disclosure. It thoroughly covers side effects (non-idempotent, new render_id, D1 usage_log insert), the current stub behavior, APS scopes, rate limits, and error handling. This is far more transparent than typical tool descriptions.

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 (purpose, when to use, scopes, rate limits, errors, side effects) and is front-loaded with the core function. While it includes generic APS rate-limit and error details that add length, each section provides useful context with minimal waste.

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 (stub pipeline, non-idempotent behavior, no output schema), the description is thoroughly complete. It explains return values, side effects, error semantics, rate limits, and alternatives, making the tool fully actionable without additional external information.

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%, and the schema already includes detailed descriptions for all five parameters. The tool description mentions entourage and landscaping, which maps to booleans, but doesn't add new meaning beyond the schema definitions. Baseline of 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?

The description clearly states the tool's function: 'Queue a Lumion-style architectural visualization still render' and specifies the return values (render_id and preview_url). It distinguishes itself from sibling tools by explicitly comparing Lumion's lush entourage to Twinmotion's cleaner look.

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' and 'When NOT to use' guidance, naming alternatives such as get_viewer_link for real-time viewing and twinmotion_walkthrough for video. This gives the agent clear decision 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, the description carries full burden and excels. It discloses that the endpoint currently responds with a 'stub job descriptor' rather than performing an actual render, details side effects ('NON-IDEMPOTENT', mints new render_id, inserts D1 usage_log), error codes (401/403/404/429/5xx), rate limits, and required APS scopes. This is far beyond typical 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?

The description is well-structured with clear sections (purpose, when/when-not, scopes, rate limits, errors, side effects) and front-loaded with a concise one-sentence purpose. While lengthy, each section carries unique operational information needed to use the tool correctly; the length is justified by the tool's current stub status and future behavior.

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 is fully self-contained for a tool with no output schema and no annotations. It defines return values (render_id, preview_url), current stub behavior, side effects, error handling, rate limits, scopes, and explicit alternative tools. It also notes future pipeline behavior and emphasizes the 'translated model' prerequisite, making it complete for an agent to decide and invoke.

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 the baseline is 3. The description adds no additional parameter meaning beyond listing control categories ('time-of-day, weather, season, and resolution') that already appear in the schema. It does not enhance the schema's examples or field 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 first sentence specifies a concrete action: 'Queue a photorealistic Twinmotion-style still render of a translated model' with render controls. It clearly differentiates from siblings by stating this is for 'still renders' and explicitly provides alternatives (get_viewer_link for real-time, twinmotion_walkthrough for moving cameras).

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 dedicated 'When to use' and 'When NOT to use' sections, presenting explicit use cases (hero still for proposals/client decks) and exclusions with alternatives (real-time interactive rendering -> get_viewer_link; moving camera -> twinmotion_walkthrough; expecting bytes -> returns URL). It also warns that the pipeline is a stub today, setting expectations.

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 fully discloses behavioral traits: it is currently a stub that responds synchronously, is non-idempotent (mints a new video_id per call), inserts a usage_log row, and outlines future scope changes. It also documents error codes, rate limits, and side effects, going far beyond basic safety hints.

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?

Although the description is long, it is well-structured with clear sections (When to use, When NOT to use, APS scopes, Rate limits, Errors, Side effects) and front-loaded with the main purpose. Every sentence provides actionable information, and the use of labels makes it scannable despite its length.

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 all essential aspects: what it does, when to use/not use, return values (video_id, download_url), current stub behavior, side effects, error handling, and rate limits. Given no output schema, it adequately explains the expected response, making the tool fully comprehensible 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?

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds a useful precondition not in the schema: the model must be 'translated' (processed by Model Derivative) for the tool to work. This goes beyond the schema's generic 'model to animate' and justifies a slightly higher score.

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 uses a specific verb+resource ('Queue a cinematic Twinmotion-style fly-through video of a translated model') and clearly distinguishes from siblings by specifying when NOT to use it (for real-time interactivity use get_viewer_link, for still images use twinmotion_render). It also states the return values (video_id and download_url), leaving no ambiguity about the tool's core function.

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 name alternative tools (get_viewer_link, twinmotion_render) and provide concrete use cases (marketing/pre-con video scripted from an agent workflow). This is the gold standard for 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?

No annotations exist, so the description must disclose all behavioral traits. It does so thoroughly: non-idempotency, side effects (bucket creation, timestamped object key, D1 inserts), prerequisites (public URL), rate limits, error classes, and scope requirements. This is exceptional transparency for a mutation tool.

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 every section serves a purpose: action, format list, usage guidance, exclusions, scopes, rate limits, errors, and side effects. The structure uses clear label prefixes and bullet-like separations, making it scannable despite the length. Minor redundancy exists (e.g., format list is long and somewhat repeated in schema examples), but overall well-organized.

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 complex tool with no annotations and no output schema, the description is extremely thorough. It covers all aspects an agent needs: verb/resource, return values (URN/viewer/QR), prerequisites (public URL, 100MB limit), error handling, rate limiting, side effects, and sibling differentiation. The only minor gap is the lack of explicit response structure beyond the return line, but the description still conveys the necessary execution context.

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 all three parameters with 100% coverage. The description adds value by reinforcing key constraints (max 100MB, direct fetch, extension-based tiering, timestamped key) and clarifying edge cases (presigned URLs work, ASCII-only filenames). This goes beyond simple schema repetition, though the schema already does 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?

The description opens with a specific verb ('Ingest') and clear resource ('3D model from a public URL into APS OSS') plus the secondary action ('kick off a Model Derivative translation job'). It explicitly states return values (URN, viewer link, QR code), and the format list distinguishes it from sibling tools like get_model_metadata 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?

Dedicated 'When to use' and 'When NOT to use' sections with concrete examples (S3 presigned URL, GitHub raw) and explicit exclusion scenarios (local disk, behind auth). It also names get_model_metadata as the alternative for re-translation, which is actionable 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?

No annotations are provided, so the description carries full burden. It discloses non-idempotency, session_id minting, D1 usage_log insertion, APS scope requirements, rate limits, and error handling. This is thorough behavioral disclosure beyond what annotations would typically provide.

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 labeled sections for purpose, usage, scopes, rate limits, errors, and side effects. It front-loads the main purpose in the first sentence and every section earns its place with actionable information.

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 the tool's output (session URL and QR code) and thoroughly covers selection criteria, side effects, permissions, and error conditions. For a tool with this complexity, the description 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 description coverage is 100%, and each parameter already has a clear description with examples. The tool description itself adds no additional parameter semantics beyond what the schema already provides, so the baseline of 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?

The description opens with a specific verb 'Create' and names the resource ('shareable WebXR AR passthrough session URL and QR code'). It clearly differentiates from sibling tools by explicitly stating when NOT to use it and directing to xr_launch_vr_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?

Includes a dedicated 'When to use' section with two concrete scenarios (jobsite walkthrough, tabletop mini-model) and a 'When NOT to use' section naming exact alternative tools. This is exemplary 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?

No annotations are present, so the description fully carries the transparency burden. It discloses side effects (non-idempotent, session_id minting, D1 usage_log insert, no APS resources created), APS scopes, rate limits, and detailed error codes with remedies. This goes well beyond typical descriptions.

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 logically structured into clear sections (purpose, when to use, when not to use, scopes, rate limits, errors, side effects). Every sentence delivers actionable information; there is no redundancy or filler.

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, no annotations, and no output schema, the description covers all critical aspects: purpose, usage constraints, scopes, rate limits, error handling, and side effects. It even notes that rendering happens in the user's Quest browser, setting correct expectations.

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 examples and defaults for all five parameters. The description adds a useful note that session_id is generated server-side, but it does not add per-parameter meaning beyond what the schema already provides. 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?

The description opens with a specific verb and resource: 'Create a shareable WebXR VR walkthrough session URL (and Meta Quest oculus:// deep link + QR code) for a translated model.' It clearly distinguishes from siblings by explicitly naming xr_launch_ar_session and get_viewer_link as alternatives for non-headset users.

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' and 'When NOT to use' sections, including the exact alternative tools (xr_launch_ar_session, get_viewer_link) and a prerequisite check (get_model_metadata before calling if translation may be incomplete). This is exemplary 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 provided, the description carries full burden. It discloses read-only/idempotent behavior, D1 data source, empty array fallback, rate limits, error responses, and side effects. This is exceptional coverage for a simple list tool.

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 labeled sections and front-loaded purpose. However, it includes irrelevant rate limit information (Model Derivative, OSS uploads) and 'not applicable' error entries that add noise and do not pertain to this tool.

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 is unusually complete. It covers use cases, exclusions, data source, ordering, empty-array behavior, auth requirements, rate limits, error handling, and side effects, making the tool self-contained 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 both parameters described as 'reserved' and 'currently not applied.' The tool description adds no additional parameter-level detail beyond the schema, so the baseline 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 opens with a specific verb ('List'), resource ('last 20 VR/AR sessions'), source ('launched via xr_launch_vr_session and xr_launch_ar_session'), and ordering ('creation time desc'). It clearly distinguishes from sibling launch tools and other list tools like acc_list_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?

Provides explicit 'When to use' and 'When NOT to use' sections, including what details are not available (join URL, features) and where they live. Names alternatives indirectly by referencing the original launch response, giving clear decision criteria.

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