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

Annotations declare readOnlyHint=false and destructiveHint=true, so the agent knows this mutates content. The description adds only that annotation extents are ignored, but does not disclose what gets repositioned, whether the operation is reversible, or what document state is required. For a destructive mutation, that is a significant behavioral gap.

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 a single front-loaded sentence with no wasted wording. It is concise, but arguably too terse for a five-parameter destructive tool, leaving key details unstated.

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?

An output schema and annotations exist, so the description need not cover return values or basic safety hints. However, given five parameters with zero schema descriptions and a destructive mutation, the description is not complete enough to help an agent invoke the 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 description coverage is 0%, and the description only vaguely maps target sheets and a reference sheet to the parameters. It does not explain main_sheet_number, target_sheet_numbers defaults, or the three boolean parameters align_legend, align_titleblock, and apply_crop_scope_box, so it fails to compensate for the undocumented 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 states a specific verb and resource: aligns viewports on target sheets to a reference sheet. This clearly distinguishes the tool from sibling read/list/view tools. It is slightly ambiguous about whether main_sheet_number is the reference sheet, but the core purpose is clear.

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 explains what the tool does but gives no explicit guidance on when to use it, when not to use it, or what prerequisites are required. There are no sibling alternatives named, though no direct sibling for viewport alignment is present.

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?

Annotations declare destructiveHint=true and readOnlyHint=false, but the description reads as a passive analysis ('matches... returns') and never warns that it may alter the model's grid/calibration state. It also omits permission/setup requirements and whether an existing calibration is overwritten. With a destructive annotation, at minimum the description should tell the agent what gets changed.

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?

One front-loaded sentence with no filler, so nothing needs trimming. However, brevity here comes at the cost of under-specification rather than efficiency.

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?

An output schema exists, so return values need no explanation, but for a destructive five-parameter tool with zero schema documentation the description leaves far too much unstated: no preconditions, no parameter meaning, and no disclosure of model mutation.

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?

Five parameters at 0% schema description coverage, and the description explains none of them — not page_number (required), method, pdf_path, level_name, or overall_page. It also never clarifies the distinction between page_number and overall_page, which is the most likely misuse vector.

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?

States a specific verb and resource: matching PDF drawing coordinates to Revit grids, plus the outputs (calibration points, scale, error). It is distinguishable from siblings like parse_pdf_structural_plan, which parse rather than calibrate against the model.

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?

No indication of when to use this versus the PDF parsing tools, no prerequisites such as needing a document open or a level selected, and no note on what to do when calibration fails. The agent must infer everything from the name.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. However, the description does not explain the destructive implications, what gets replaced or appended, how duplicates are handled, or what dry_run does, which are critical for a batch mutation with conflicting-sounding options.

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?

It is a single sentence with no wasted words, but it is under-specified for a complex tool rather than appropriately structured. The core action is front-loaded, but important qualifiers are absent.

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 destructive batch creation tool with 12 parameters and an output schema, the description is far too thin. It omits prerequisites, duplicate/replacement behavior, dry-run semantics, and how the project type mapping works, leaving major operational 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 0% across 12 parameters. The description only implicitly maps to the walls, pad_footings, and strip_footings arrays and does not explain level_name, dry_run, allow_duplicates, replace_existing, append_to_existing, offsets, or wall type mapping.

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 names a specific verb and resources ('Creates footings, walls and strip footings') and mentions the data source. It does not differentiate from the close sibling batch_create_structural_walls_and_foundations, leaving ambiguity about which batch tool to choose.

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?

There is no guidance on when to use this tool versus the similar batch structural tools, no prerequisites, and no mention of when not to use it. The agent must infer selection from the name alone.

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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write/destructive nature is covered structurally. The description does add two genuinely useful behavioral facts: the operation is atomic ('one transaction') and gated by preflight checks. It stops short of disclosing what replace_existing overwrites or how force bypasses checks.

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?

A single front-loaded sentence with zero filler and the atomicity guarantee placed where an agent will read it first. It is efficient rather than bloated, though efficiency here shades into under-specification.

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 destructive, 12-parameter batch mutation with no schema descriptions, one sentence is far from sufficient. The output schema excuses it from describing return values, but nothing tells the agent what the nested column/beam objects must contain or how duplicate/overwrite conflicts are resolved.

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 0% across 12 parameters, so the description must carry the load and does not. It only implies the columns/beams arrays (already obvious from names) and vaguely gestures at dry_run via 'preflight checks', leaving force, replace_existing, allow_duplicates, source_tag, top_level_name, and the three base_*_family parameters entirely unexplained.

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?

States a specific verb (creates) plus two concrete resources (structural columns, beams) and adds sequencing ('columns then beams'). It is distinguishable from siblings like batch_create_structural_slabs or batch_create_footings_and_walls by the element types it produces, though it never names those siblings explicitly.

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?

There is no guidance on when to choose this batch tool over the sibling batch_* creators, nor any stated prerequisites beyond the vague phrase 'preflight checks'. The flags that clearly change usage decisions (dry_run, force, replace_existing, allow_duplicates) are never mentioned.

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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is known. The description adds useful context that slabs and openings are handled atomically in one transaction. It does not explain what existing geometry may be replaced, permission requirements, or failure 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?

A single front-loaded sentence with no wasted clauses. It is structurally efficient, though its brevity contributes to the missing parameter and behavioral detail.

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 destructive batch-creation tool with two required parameters, zero schema coverage, and an array of arbitrary slab objects, the description is far too thin. The output schema may cover return values, but the input contract and transaction semantics remain largely unexplained.

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 0%, and the description does not explain either required parameter. It implies 'slabs' are created but does not describe the slab object shape, and it never mentions 'level_name' or how it controls placement.

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 and resource: creates structural slabs and cuts openings. It clearly distinguishes the tool from siblings that handle framing, columns, footings, walls, or foundations. It does not explicitly name alternatives, but the resource scope is 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?

There is no guidance on when to use this tool versus related batch creation siblings, no prerequisites, and no exclusions. 'In one transaction' hints at atomicity but does not tell an agent when this is preferable to separate creation steps.

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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is partly covered externally. The description adds useful behavioral context by saying all creations happen 'in one transaction,' but it does not explain what destructive effects may occur, how duplicates are handled, or what happens on partial failure.

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 a single front-loaded sentence with no wasted wording. It is efficient, though extremely terse for a complex 6-parameter destructive batch operation.

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 destructive batch-creation tool with 6 parameters, 0% schema description coverage, and overlapping sibling tools, the description is too incomplete. It does not cover required inputs, parameter formats, transactional failure behavior, or why an agent should choose it over alternatives.

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 0% across 6 parameters, so the description must carry parameter meaning. It only maps the resource categories to some parameters and does not explain the required 'level_name', the default 'wall_height_mm', or the expected structure of the object arrays.

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 names a specific verb ('Creates') plus the exact structural resources ('shear walls, pile caps and pad/strip footings'), so the tool's purpose is clear. However, it does not distinguish this tool from the overlapping sibling 'batch_create_footings_and_walls'.

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 phrase 'in one transaction' implies atomic batch creation, but the description gives no explicit guidance on when to use this tool instead of sibling batch tools such as 'batch_create_footings_and_walls' or 'batch_create_structural_framing_and_columns'.

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?

The description says the tool 'scans' for duplicates, which implies an inspection-only operation, while annotations declare destructiveHint=true and readOnlyHint=false. It does not disclose what destructive action may occur, what gets changed, or whether duplicates are merely reported or actually removed/modified.

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 a single front-loaded sentence with no wasted wording. It communicates the scan targets and condition efficiently.

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 an output schema exists and no parameters need explanation, the description omits the critical destructive behavior implied by annotations. An agent cannot tell whether this tool reports, deletes, or otherwise modifies duplicate/overlapping elements.

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 has zero parameters, so there is no parameter semantics burden on the description. The baseline for a no-parameter tool 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 states a specific verb and resource scope: scanning columns, beams, walls, footings, and slabs for duplicates or overlaps. It is clear what the tool inspects, but it does not distinguish its role from nearby structural cleanup or modification 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?

There is no guidance on when to use this tool, when not to use it, or which alternatives to prefer. An agent can infer that it is a duplicate-checking tool, but no explicit workflow or prerequisite is provided.

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?

The annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful specificity by saying exactly what is removed—view color overrides from elements in a category—but it does not discuss reversibility, permissions, or side effects beyond that scope.

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 definition is a single front-loaded sentence with no filler. It communicates the action and scope efficiently.

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 output schema handles return values and annotations convey destructiveness, so the description need not explain those. However, for a destructive operation, it omits important context such as whether a document/view must be open, how category names are resolved, and what happens if no overrides exist.

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 is one required parameter, category_name, with 0% schema description coverage. The description implies that the parameter identifies the category whose elements are affected, but it does not explain the expected format, matching rules, or whether the category must already exist, so it only partially compensates for the missing schema 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 states a specific verb and resource: it removes view color overrides from elements in a category. This is clear enough for an agent to understand the action, though it does not explicitly differentiate the tool from related siblings such as color_splash.

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 only states what the tool does, not when to use it, when not to use it, or which alternative to choose. There is no mention of prerequisites, such as requiring an active view or document, and no routing guidance toward color_splash or other color-related tools.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds that the operation targets the active document and optionally saves, but does not explicitly warn that unsaved changes are lost if save is false.

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?

A single front-loaded sentence with no filler. It communicates the action, target, and only option efficiently.

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 simple document-close tool with annotations covering destructiveness and an output schema present, the description is nearly sufficient. The main missing detail is an explicit warning about unsaved changes when save is false.

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 sole parameter is `save`, and the description explains its semantic effect: changes are optionally saved before closing. Schema coverage is 0%, but the description compensates by giving meaning beyond the boolean type.

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?

States a specific verb (closes) and resource (active Revit document), with the optional save behavior. It is clearly distinct from open_document and save_document, though it does not explicitly name those 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?

No explicit guidance on when to use this versus save_document or when not to close. The context is implied by the operation, but the description provides no conditions, prerequisites, or 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?

Annotations already flag this as a non-read-only, destructive operation, but the description adds nothing about what that destruction means — whether existing overrides are replaced, whether it targets the current view only, or whether the operation is reversible via clear_colors. The only behavioral context offered is the 'grouped by parameter value' mechanism, which is thin for a destructive 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?

A single clean sentence with the action front-loaded and no filler. It earns its length, though it is arguably too terse for a destructive four-parameter tool rather than bloated.

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?

An output schema exists so return values need not be explained, but for a destructive tool with four undocumented parameters and no annotations beyond hints, the description leaves critical gaps: which view, how colors are assigned per group, and how to revert. It is not sufficient to invoke the tool confidently.

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 0%, so the description must carry the parameter burden, yet it explains only the idea behind parameter_name (grouping key) and vaguely gestures at colors. category_name, custom_colors (array format/ordering, null default) and use_gradient are all left undocumented in both schema and description.

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 gives a specific verb ('applies') and resource ('view color overrides on elements') plus the grouping mechanism ('grouped by a parameter value'), so the agent knows exactly what the tool does. It stops short of naming or contrasting with sibling tools like clear_colors, which is the obvious complement.

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?

There is no explicit when-to-use, no prerequisites (an open document and an active view are surely required), and no mention of clear_colors as the way to undo the effect. The agent must infer the scenario entirely from the one-line purpose statement.

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?

Goes meaningfully beyond the annotations: it discloses that code runs with the Windows user's permissions and can reach model data, files and network services, which explains why openWorldHint and destructiveHint are true. It does not cover failure modes, timeouts, or whether effects can be rolled back (undo_last exists as a sibling), but the added context is substantial.

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?

A single front-loaded sentence with the verb first and no filler. It is dense but every clause (permissions, capabilities) adds information rather than restating the name.

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?

An output schema exists so return values need not be described, and annotations already flag destructiveness and open-world access; the description fills the remaining gap with permission scope and capability scope. For a code-execution tool a note on isolation or side-effect permanence would complete it, but an agent has enough to call it responsibly.

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 0%, so the description must carry the load. It does specify the code language (IronPython), which is real semantics beyond the schema's bare 'string/Code', but the optional 'description' parameter is never mentioned and no guidance is given on code structure or entry point.

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?

States a specific verb and resource: executes supplied IronPython code inside Revit. That distinguishes it from the operation-specific siblings (place_family, modify_or_delete_elements, etc.) by implication, since this is the general-purpose escape hatch, though the description never says so explicitly.

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 phrase 'after review in Revit' implies there is a review/approval gate before execution, which is useful context. But there is no explicit statement of when to prefer this over the many dedicated sibling tools (e.g. use modify_or_delete_elements instead of writing deletion code), and no when-not-to-use guidance for a destructive tool.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds one genuinely useful behavioral fact — joins are applied in structural priority order — but never explains what the destruction means in practice: whether existing geometry/joins are overwritten, whether it is undoable, or whether it requires a loaded structural model.

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?

One well-formed sentence with the operation and its scope front-loaded and zero filler. Every clause carries 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?

An output schema exists so return values need no explanation, but for a destructive, model-altering tool the description omits preconditions, side effects on existing joins/geometry, and recovery options. Given the blast radius, it leaves too much to inference.

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 0% and the single level_name parameter is undocumented in the schema. The description only implies that the level scopes the operation; it does not say whether the name must match exactly, is case-sensitive, or must already exist, so it only partially compensates for the coverage gap.

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?

States a specific verb (joins geometry) and a specific resource set (columns, walls, beams, slabs) scoped to a level. It is clearly a structural-finalization operation, distinguishable from the batch_create_* siblings, though it does not name which sibling to run instead or after.

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?

No when-to-use guidance at all: nothing says this should follow element creation, that elements must already exist on the level, or what to do if the model is not yet structurally complete. The agent must infer timing and preconditions from sibling names alone.

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?

Annotations declare destructiveHint=true and readOnlyHint=false, so the agent knows this is not a pure read operation. However, the description does not disclose the important side effect: writing/overwriting an output PNG file, nor does it explain what is required for correct alignment or what is destroyed.

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 a single front-loaded sentence with no filler. However, conciseness comes at the cost of under-specification for a 9-parameter 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?

For a 9-parameter generation tool with no output schema and no schema parameter descriptions, one sentence is far too thin. It does not explain the output file behavior, grid-point semantics, or how the required overlay inputs relate to one another.

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 0% across 9 parameters. The description only indirectly evokes pdf_path, page_number, and level_name, and provides no meaning for grid_step_mm, pdf_grid_pt1/pt2, revit_grid_pt1/pt2, or output_png_path. It cannot compensate for the schema's total lack of parameter 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 names a specific verb and resource: it overlays modelled elements onto a source PDF page and produces an image for visual QA. That is clear enough to distinguish it from parse_pdf_* and grid-calibration siblings, though 'modelled elements' remains somewhat vague.

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 phrase 'for visual QA' hints at the use case, but there is no explicit guidance on when to use this tool instead of auto_calibrate_grids, parse_pdf_structural_plan, or other sibling tools. No prerequisites or exclusions are stated.

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?

Annotations already declare readOnlyHint, non-destructive, and closed-world, so the safety profile is covered. The description adds the active-view scoping and the optional levels/location enrichment, but omits important behavior: what happens if no view is active, and that results are capped by a default limit of 5000 and may be truncated.

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?

A single efficient sentence with the core scope front-loaded and the optional enrichments trailing. No waste, though it could carry a needed caveat about truncation without becoming bloated.

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?

An output schema exists so return values needn't be explained. However, for a list tool with a 5000-row default cap, the description should warn about truncation and the no-active-view case; those omissions leave meaningful gaps 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 coverage is 0%, so the description must compensate. It maps 'level and location information' to include_levels and include_location, but says nothing about the limit parameter or its 5000 default, leaving truncation behavior undocumented for one of three params.

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?

Clear verb+resource: 'Lists elements visible in the active view'. An agent immediately understands the operation. It doesn't differentiate itself from nearby siblings like get_current_view_info or list_revit_views, so it falls short of a 5.

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?

There is no explicit when-to-use guidance, no mention of alternatives such as get_current_view_info for view metadata, and no note on prerequisites like an active document/view. Usage is only implied by the phrase 'active view'.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered and the description correctly does not contradict it. The description adds only that the target is the 'active' view, with no detail on scope limits or freshness; with an output schema present, no further return-value disclosure is required.

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?

A single front-loaded sentence with no filler, appropriate for a no-argument read tool. It is slightly under-specified rather than verbose, leaving the sibling differentiation unstated.

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 simple, no-parameter read operation with a full output schema and read-only annotations, this is nearly complete. The only missing element an agent might want is explicit routing guidance relative to get_revit_view and get_current_view_elements.

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 there is nothing for the description to disambiguate and the baseline of 4 applies. The description does not need to explain inputs beyond confirming the implicit context is the current view.

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?

States a specific verb and resource ('Reads the active view's properties and settings'), and the word 'active' implicitly differentiates it from get_revit_view and list_revit_views, which presumably target arbitrary views. It does not name those siblings explicitly, so the distinction is inferential rather than stated.

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?

Usage is only implied by the word 'active' – an agent can infer this is the tool for the view currently open rather than a view looked up by id. There is no explicit when-to-use statement or reference to the alternatives (get_revit_view, list_revit_views, get_current_view_elements).

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful scope by listing the data categories read, but it does not mention performance characteristics, permissions, or whether the operation is expensive for large models.

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?

A single sentence that front-loads the operation and lists the returned categories without any filler. Every word contributes to telling the agent what information is available.

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?

With an output schema present and annotations covering safety, the description only needs to convey the scope of information returned, which it does. A minor gap is that it does not state whether it operates on the active document or requires a specific project 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?

There are zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the empty schema is consistent with a no-argument read operation.

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 clear verb ('Reads') and enumerates the specific data types returned (project metadata, element counts, rooms, views, sheets, warnings, linked-model info). However, it does not distinguish this tool from siblings such as get_revit_status, list_revit_views, or get_current_view_info, leaving overlap ambiguous.

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?

There is no explicit guidance on when to use this tool versus alternatives, no prerequisites (e.g., an open document), and no exclusions. The purpose implies usage, but the description offers no routing information.

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?

Annotations already declare readOnlyHint, non-destructive, and closed-world, so safety is covered. The description adds the useful detail that it probes connectivity to the bridge and whether a document is loaded, but says nothing about failure modes (bridge down, no document open) or latency for a health probe.

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?

A single short sentence, front-loaded with the verb and both pieces of information returned. No 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?

An output schema covers the return values and annotations cover safety, so the description only needs to say what is checked, which it does. It could go further by telling the agent to call this before document-dependent tools, but nothing critical 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 tool takes zero parameters, which is the baseline-4 case. The description also implicitly signals a no-argument call by describing only read scope.

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?

Names a specific verb (reads) and two concrete resources: bridge health and active document availability. This distinguishes it from data-reading siblings like get_revit_model_info or get_current_view_info, though the description does not explicitly say so.

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?

There is no explicit statement of when to call this versus connections-checking siblings (list_revit_installations) or document-state siblings (get_revit_model_info). Usage is only implied by 'health' and 'availability', which an agent must infer as a pre-flight check.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful behavioral detail that the output is a PNG image, but it does not disclose where the image is written or returned.

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?

A single compact sentence with the action and output format front-loaded. There is no filler 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?

The tool is simple and its annotations cover safety, but with no output schema the description should say what the PNG export returns or where it is saved. It also lacks guidance on obtaining valid view names, leaving a meaningful gap 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 0%, so the description must carry the burden for the single view_name parameter. It only implies that the parameter is a view name; it does not explain the expected format or how to discover valid names (e.g., via list_revit_views).

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 ('Exports') and names the resource ('a named model view') plus the output format (PNG image). It is clear enough to distinguish an image export from list_revit_views or get_current_view_info, though it does not explicitly name those 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?

The description states what the tool does but gives no guidance on when to use it versus alternatives like list_revit_views or get_current_view_info. It also omits prerequisites such as whether the view must already be open or active.

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?

Annotations already declare readOnlyHint=false, openWorldHint=true, destructiveHint=true, so the risk profile is partly structured. The description adds the readiness-check behavior and the optionality of opening a file, but never explains what makes this 'destructive' (e.g., replacing an existing instance, losing unsaved state) or what credentials/installations are required.

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?

A single front-loaded sentence that names the core action first and the two optional behaviors after. No padding.

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?

An output schema exists so return values need not be described, but with four undocumented parameters, a destructive/open-world annotation, and no mention of preconditions (is Revit already running? what if the version is installed twice?), the definition leaves notable 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 0%, so the description must carry parameter meaning. It only maps to version ('installed Revit version') and file_path ('opens a model file'); timeout and language are completely unexplained, as is the accepted format for version selection.

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?

States a specific verb+resource ('Starts an installed Revit version') and enumerates the two side behaviors (optionally open a model, check bridge readiness). An agent can distinguish it from open_document and get_revit_status, though the description never names those siblings explicitly.

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 implied usage (bring Revit up before other operations, optionally loading a model) is readable from the wording, but there is no explicit when-to-use/when-not guidance and no routing to alternatives like open_document for an already-running instance.

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?

Annotations already declare that this is a non-destructive read-only operation, so the description does not need to cover safety. It adds some useful behavioral context by mentioning sample values, but does not explain category matching behavior, expected failures, or how categories are identified.

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 a single front-loaded sentence with no filler. It is appropriately sized for a simple list operation, even if it leaves semantic gaps elsewhere.

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 tool has annotations and an output schema, which reduce the burden on the description. However, the sole input parameter is undocumented and the description does not explain what a category name should be or where valid names come from, leaving a meaningful gap for 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 is one required parameter, category_name, with 0% schema description coverage. The description only says the tool works "for a category" and provides no format, source, casing, or valid-value guidance for the parameter, so it does not compensate for the schema gap.

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 a specific verb and resource: it lists element parameters and sample values for a category. It is understandable apart from most siblings, though it does not explicitly differentiate itself from tools like list_family_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?

It implies the tool is used for a category, but gives no explicit when-to-use guidance, prerequisites, or alternatives. It does not say how this differs from list_family_categories or when an agent should prefer it.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful 'loaded' qualifier (only families present in the project), but does not mention the default limit or any pagination/return-count 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?

A single front-loaded sentence with no filler. Efficient, though its brevity is part of why parameter coverage is thin.

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?

An output schema exists, so return values need not be explained. However, for a two-parameter list tool with 0% schema coverage, the description omits the limit/pagination semantics, leaving the agent guessing about result-set size behavior.

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 0%, so the description carries the burden. It explains the name-filter (contains) semantically but leaves the limit parameter and its default of 50 completely undocumented in both schema and description.

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?

States a specific verb ('Lists') and resource ('loaded family types'), with a scoping qualifier ('loaded') and optional name filtering. It is clear what the tool does, though it does not explicitly contrast with the close sibling list_family_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?

No when-to-use or when-not-to-use guidance is given, and no alternative is named (e.g. list_family_categories or place_family). The phrase 'optional name filtering' only weakly implies how the contains parameter should be used, leaving the agent to infer routing.

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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear without the description. The description adds only the useful qualifier that categories are those of loaded families, not all possible families; it does not describe rate limits, ordering, or other 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 a single front-loaded sentence with no wasted words. It states the action and scope immediately.

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 zero-parameter read-only listing tool with annotations and an output schema, the description covers the essential scope. It could mention how this relates to list_families or list_category_parameters, but no critical invocation detail 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 tool takes zero parameters, so there is no parameter semantics burden on the description. The schema is empty and fully self-documenting for this tool.

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 and resource ("Lists categories") scoped to "loaded families." This is clear enough to distinguish it from list_families, which lists families rather than their categories, though the relationship between the two siblings could be stated explicitly.

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?

No guidance is given about when to use this tool instead of list_families, list_category_parameters, or other listing tools. The phrase "of loaded families" provides a scope hint but not an explicit usage condition or exclusion.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds only that elevations are returned, which is minimal but not contradictory; with an output schema present, further return-value detail is not required.

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?

A single short sentence that is front-loaded and waste-free. It communicates the tool's scope without unnecessary elaboration.

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 zero-parameter read-only list tool with full annotations and an output schema, the description is sufficient to call it correctly. A brief indication of when to prefer it over related list/get tools would make it 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?

The tool takes zero parameters, so there is nothing for the description to document. The baseline of 4 applies; no parameter-related clarity is missing.

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 clear verb+resource pair ('Lists model levels') and adds the useful detail that elevations are included. It implicitly distinguishes itself from sibling view/family tools, though it does not explicitly contrast with them.

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?

There is no guidance on when to call this tool versus alternatives such as get_revit_model_info or list_revit_views. The description gives implied context only, leaving the agent to infer usage.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only that results include executable paths, which is modest context beyond the annotations and says nothing about whether Revit must be running or how installations are detected.

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?

A single front-loaded sentence with no filler; every word (versions, executable locations) carries information about the result.

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 zero-argument read-only discovery tool with an output schema present, this is close to sufficient — return-value structure is documented elsewhere. The only gap is the absence of a note on the no-running-instance precondition, which matters given the sibling set.

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 the baseline is 4; there are no argument semantics for the description to explain. The description correctly doesn't invent or discuss 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?

States a specific verb and resource ('Lists installed Revit versions') plus the payload ('their executable locations'), which is enough to distinguish it from siblings like get_revit_status or launch_revit. It stops short of explicitly naming those siblings as alternatives, so it is clear but not maximally differentiating.

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?

Usage is only implied: an agent can infer this is the discovery tool to call before launch_revit, but the description never says when to use it or that it requires no running Revit instance (unlike most siblings). No exclusions or alternatives are stated.

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?

Annotations already declare this as a safe, read-only, non-destructive operation. The description adds useful behavioral scope by saying only exportable views are listed and that results are grouped by view type. It does not add details such as pagination or permissions, but those gaps are minor given the annotations and the existence of an output 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 a single front-loaded sentence with no wasted words. It communicates the key scope and grouping behavior efficiently.

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 zero-parameter, read-only listing tool with annotations and an output schema, the description is largely complete. It states the scope and grouping. The main missing element is guidance on when to choose this tool over sibling view-inspection tools.

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 has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics.

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 gives a specific verb and resource: it lists exportable model views. It also states the grouping behavior by view type. It is clear, but it does not explicitly distinguish this tool from the sibling get_revit_view, which likely retrieves a single view.

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 states what the tool does but gives no guidance on when to use it instead of alternatives such as get_revit_view or get_current_view_info. It also provides no exclusions or prerequisites.

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?

The annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive mutation. The description confirms deletion/movement and adds the visual-QA remediation context. It does not disclose whether deletions are reversible, how moves are applied, or any permission or ordering constraints.

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 a single front-loaded sentence with no wasted wording. However, for a destructive two-parameter tool it is too bare to provide useful structure, and the brevity leaves critical usage and parameter details unaddressed.

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?

An output schema exists, so return values need not be described. But with zero schema description coverage and destructive annotations, the description should do more to explain parameter semantics, permanence of deletion, and when this should be used instead of related tools. It is not complete enough for safe 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 0% for two parameters. The description only vaguely implies deletion through 'listed elements' and movement through 'moves,' but it does not explain delete_ids, move_vectors_mm, their formats, or how the two operations interact.

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 pair and resource: 'Deletes or moves listed elements.' It also ties the action to 'issues found during visual QA,' which gives useful purpose context. It does not explicitly differentiate this tool from the related visual QA sibling, but the action itself is clear.

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?

Usage is implied through 'to fix issues found during visual QA,' suggesting it should follow visual QA discovery. However, it gives no explicit when-to-use/when-not-to-use guidance, no prerequisites, and does not name alternatives such as undo_last or generate_visual_qa_overlay.

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?

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the safety profile is known. The description adds that opening may also audit or detach from central, which is meaningful beyond the annotations. It does not disclose what detaching does to the file's worksharing state, whether the opened document becomes the active one, or how failures surface.

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?

A single front-loaded sentence with no filler; the operation and its optional modifiers come first. It is not padded, though the brevity trades away useful detail.

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?

An output schema exists, so return values need not be described, and the tool itself is conceptually simple. But with zero schema description coverage on three parameters and a destructiveHint=true annotation, the description should at minimum explain the consequences of detach and the expected path form.

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 0%, so the description must carry the parameter meaning and it largely does not. It names 'audit' and 'detach' but never explains their effect or tradeoffs, and 'file_path' — the only required parameter — is never characterized (expected .rvt local path, central model path, etc.).

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?

States a specific verb and resource ('Opens a specified Revit document') plus the two optional modes of that operation. It is clearly distinct from close_document/save_document by the verb, but it never names those siblings or states the boundary explicitly.

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?

There is no guidance on when to open versus when to use launch_revit, get_revit_status, or close_document, and no prerequisites (e.g., Revit must be running, file must exist locally). The word 'optionally' hints that audit/detach are elective but gives no conditions for choosing them.

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?

The annotations mark this as destructive and not read-only, but the description only says it 'Extracts' elements, giving no warning that it may create, modify, or delete anything. It adds useful context about vector PDFs and Revit mm coordinates, but omits the destructive behavior and calibration 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 a single front-loaded sentence with no wasted words. However, its brevity leaves major gaps for a tool with 10 parameters and destructive semantics.

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 names the extracted elements and units, but it is not complete enough for a complex 10-parameter destructive tool. It omits critical parameter meanings, calibration expectations, and side-effect disclosure, even though the output schema can cover return values.

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 10 parameters with 0% schema description coverage, and the description explains none of them. It does not clarify pdf_path, page_number, the grid calibration point parameters, the drawing-area bounding box, or the default thickness 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 gives a specific verb, 'Extracts', and names the exact foundation elements, source type, and coordinate unit. It clearly states what the tool does, though it does not explicitly distinguish itself from sibling parse_pdf_structural_plan.

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 only states the tool's function. It gives no guidance on when to choose this tool over parse_pdf_structural_plan or the batch creation tools, no prerequisites, and no exclusions.

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?

The description frames this as a read/extract operation, yet annotations declare destructiveHint=true and readOnlyHint=false, and the text never explains what is written or altered in the model. The only added context is the Revit coordinate system and mm units; there is no disclosure of side effects, required grid alignment inputs, or failure modes.

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?

A single front-loaded clause with no filler; the units and coordinate frame come first. It is efficient but so terse that key information is simply absent rather than condensed.

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 12-parameter extraction tool with a destructive annotation and no schema coverage, one sentence is far too thin. An output schema exists so return values needn't be explained, but the calibration workflow (grid point pairs, drawing area) and the destructive side effects must be.

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 0% across 12 parameters, so the description must compensate. It only clarifies units and coordinate frame for the *_mm parameters; pdf_path, page_number, level_name, the pdf/revit grid point pairs, drawing area points, include_slabs, require_beam_tag, and default_slab_thickness_mm are all left unexplained.

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?

States a specific verb and resource ('Extracts columns, beams, slabs and openings from a vector PDF plan') and adds the coordinate system and units. It is distinguishable from parse_pdf_foundation_plan by the element types extracted, though the difference is not made explicit.

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?

No when-to-use guidance, no prerequisites (e.g. that the PDF must be a vector plan, or that grid points must be supplied for calibration), and no routing to the sibling parse_pdf_foundation_plan for foundation sheets.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this mutates the model. The description adds real context beyond that: the family must already be loaded, and properties are applied on placement. It does not say what happens on failure, whether partial placement can occur, or what units the coordinates use.

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?

A single efficient sentence with the action and both outcomes front-loaded and zero filler. Brevity is appropriate, though it comes partly at the cost of the missing parameter detail noted elsewhere.

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 an 8-parameter mutation tool with 0% schema description coverage, the description is thin: units, coordinate frame, rotation convention, and type/level selection are all unexplained. An output schema exists, so return values need not be described, but the input-side gaps are substantial.

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 0% across 8 parameters, so the description carries the full burden. It only gestures at 'coordinates' (x/y/z) and 'properties'; it says nothing about rotation, type_name, level_name, or how family_name relates to the loaded family list, leaving most parameters as bare titles.

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?

States a specific verb ('Places') and resource ('a loaded family instance') plus the two things it does: position at coordinates and set properties. It does not explicitly contrast with siblings like batch_create_structural_framing_and_columns or modify_or_delete_elements, so differentiation relies on the reader's own comparison.

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?

There is no explicit when-to-use guidance, no mention of alternatives (e.g., the batch creation tools), and no exclusions. The phrase 'loaded family' hints that list_families must run first, but the prerequisite is only implied, not stated.

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?

Annotations already flag destructiveHint=true and openWorldHint=true, so the bar is lower, but the description adds nothing about what the destruction means: an in-place save overwrites the original file, and a file_path save overwrites or creates a file on disk. It also does not say whether a confirmation or elevated permission is required. It does correctly reflect the in-place vs. new-file distinction, so it is not contradictory.

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?

One sentence, front-loaded with the verb and resource, with no filler. It is efficient, though slightly terse for a destructive write operation.

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?

An output schema exists so return values need not be explained, and the parameter semantics are covered. What is missing for a destructive, open-world mutation is error behavior (no active document), overwrite handling for an existing file_path, and any prerequisite about an open document.

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 0% and the single parameter has a null default, yet the description explains both branches: no path means save in place, a given path means write to that file. This is the main value the description adds and it compensates well for the bare 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?

States a specific verb and resource ("Saves the active document") and adds the two modes of operation, so it is clearly distinguishable from open_document and close_document. It does not differentiate against sync_with_central, which is the closest sibling in a Revit context.

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?

No indication of when to prefer this over sync_with_central or close_document, and no precondition such as "a document must already be open." The agent must infer that saving to central is a different tool.

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?

Annotations already declare destructiveHint=true, openWorldHint=true, and readOnlyHint=false, so the agent knows this is a risky write. The description adds the meaningful precondition that the model must be 'active' and workshared, plus that relinquishing is involved. It stops short of explaining what 'relinquish' actually discards or that relinquish_all defaults to true, which is the behavior most likely to surprise an agent.

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?

A single front-loaded sentence with no filler, which is good structurally. It is economical to the point of under-specifying a destructive three-parameter operation, so brevity here is not unambiguously a virtue.

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?

An output schema exists, so return values need no explanation. However, for a destructive, open-world sync with three fully undocumented parameters and zero usage guidance, the description leaves material gaps an agent would need to fill before invoking it safely.

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 0% — three parameters (comment, compact, relinquish_all) are documented in name only, with no enums and no descriptions. The phrase 'requested relinquish options' gestures at relinquish_all but says nothing about comment or compact, so the description does not compensate for the coverage gap.

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?

Specific verb (synchronizes) plus specific resource (active workshared model with central), which clearly separates it from save_document or close_document among the siblings. It does not explicitly name how it differs from those adjacent save/close operations, keeping it short of a 5.

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?

There is no statement of when to use this versus save_document or close_document, no prerequisites (e.g., the model must be workshared, and the user should have central access), and no mention of what happens on failure. Usage is only implied by the verb.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds useful scope by specifying that it undoes only the last committed action and only in the active document, but it does not explain repeatability, error behavior, or whether the undo is itself reversible.

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?

A single, front-loaded sentence with no unnecessary words. Every part of it contributes to understanding the 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?

This is a simple zero-parameter tool with annotations covering its destructive nature and an output schema available. The description sufficiently explains the scope, though it could mention behavior when no action is available to undo.

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 takes zero parameters, so there is no parameter semantics to document. The baseline for a zero-parameter tool is 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 ('Undoes') and resource ('the last committed action') with clear scope ('in the active Revit document'). It is unambiguous, though it does not explicitly differentiate from any sibling 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 defines what the tool does but gives no explicit guidance on when to use it, when not to use it, or alternatives. Usage is only inferred from the tool's purpose.

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