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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial behavior beyond them: no matches return groups=[], invalid field/filter names raise errors even on empty results, failures (missing document, read failure, timeout) error out with no partial data, and skipped/skippedCount signals incompleteness with a 100-entry cap. It also resolves multi-instance ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then return shape, then usage routing and error semantics. Dense lines but each carries distinct information; the only mild cost is the slightly sprawling list of error/edge cases relative to the core aggregation purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the description need not explain return structure, yet it still documents units, error behavior, instance selection, and skipped semantics. For a 15-parameter aggregation tool with one required field, this covers everything an agent needs to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, and the description adds real meaning: group_by takes one or two distinct fields, sum_field controls numeric aggregation, and it documents unit conventions (mm/m2/m3) and null sum/average for non-numeric groups. These supplement rather than merely repeat the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (summarize matching elements by one or two fields) and clarifies it produces counts/breakdowns rather than rows. Explicitly distinguishes itself from the sibling revit_query_elements, which the agent can use to pick the right tool without opening schemas.

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?

Gives a hard prerequisite (call revit_list_catalog first), a preference rule ('prefer this tool for counts and breakdowns'), and the alternative condition ('revit_query_elements only for individual rows'). It also names a prerequisite for a specific case (for area totals, group by level and select the area scheme).

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, idempotentHint=false and readOnlyHint=false, so the safety profile is partly covered. The description adds genuinely useful context beyond them — that geometric alignment does not create a monitor relationship or trigger Coordination Review warnings — but it does not disclose the destructive scope (what happens to pinned or existing datums) or how rollback is actually performed.

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?

Two tight sentences, front-loaded with the core action and followed by the one behavioral caveat. Nothing is padded, though the extreme brevity against a 17-parameter mutation tool makes it under-specified rather than exemplary.

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, non-idempotent, 17-parameter tool this is far too thin. An output schema exists so return values need not be described, but the description gives no guidance on the many naming/creation/tolerance parameters an agent must set to call it 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 only 6% across 17 parameters, so the description carries the burden and fails: 'optional creation' and 'rollback preview' loosely hint at create_missing and dry_run, but kinds, prefix/suffix, name_map, tolerance_mm, include_pinned, grid_type/level_type and reuse_matching are entirely unexplained anywhere.

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 ('Align') and resources ('host grids and levels') against a named target ('a loaded link'), plus the optional creation and preview behavior. An agent can distinguish it from the sibling revit_compare_link_datums (compare vs. align), though the description never explicitly contrasts 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 when-to-use guidance, no stated prerequisites (a link must be loaded, presumably compared first), and no exclusions for when to prefer revit_compare_link_datums or revit_shared_coordinates. 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?

The annotations only give the coarse safety profile (destructive, non-idempotent, not read-only); the description adds substantive behavior: atomicity with a single undo step, rollback on first failure, the 50-action ceiling, and the precise dry_run semantics (executes, rolls back, returns the same verification block without changing the model). That is exactly the kind of operational detail annotations cannot convey.

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?

Three short sentences, front-loaded with the core transactional guarantee before the dry_run and document details. No filler, no repetition of annotation content, and each sentence carries distinct 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 not be described, and the description still usefully references the verification block. Combined with the annotations it covers safety, atomicity, rollback, limits, and multi-document targeting. The remaining gap is the relationship to the sibling async batch tools, which the agent must resolve elsewhere.

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 only 33%, but the description compensates well for the undocumented dry_run parameter by explaining that it executes and rolls back while returning the same verification block. The document parameter is already fully documented in the schema and the description only echoes its rejection behavior; steps is largely covered by the schema's maxItems/enum, though the description restating 'up to 50' adds little.

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 with scope: 'Execute up to 50 actions with one undo step.' An agent immediately knows this runs a transactional batch of model mutations. It does not, however, distinguish itself from the sibling batch tools (revit_batch_start, revit_batch_status, revit_batch_cancel, revit_batch_fetch) or explain why one would batch rather than call the individual action 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?

Some usage context is implied through the dry_run and document explanations, which tell the agent when to preview and when to disambiguate a target model. But there is no explicit guidance on when to use this batch tool versus the single-action siblings or versus revit_batch_start/status/cancel, so the agent must infer the 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 description states the tool 'persist[s] cancellation' and stops models from running — an environment-mutating action — while annotations declare readOnlyHint=true. This is a direct contradiction. The one useful nugget ('prevent unstarted models from running', implying in-flight models continue) is outweighed by the conflict.

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 with no filler, front-loaded with the core action. It is efficient, though the terse phrasing contributes to the ambiguity 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?

An output schema exists so return values need not be described, but for a cancellation tool the description omits what happens to already-running models, whether repeated calls are safe (annotation says idempotentHint=false), and any permission requirements. Combined with the readOnly contradiction, the definition is not complete enough to call 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% and the description says nothing about run_id — not its format, nor where to obtain it (presumably from revit_batch_start). With a low-coverage schema the description is expected to compensate, and it does not.

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 name and title ('Cancel batch collection') identify the resource and the description adds the scope ('persist cancellation and prevent unstarted models from running'). However, the phrasing is indirect — it never plainly says 'cancels a batch run' — and it does not distinguish itself from siblings like revit_batch_start, revit_batch_status, or revit_batch_fetch.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as checking revit_batch_status before cancelling or using revit_batch_fetch to inspect results. The agent must infer the trigger condition entirely.

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, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds one genuine trait beyond the annotations ('without overwriting'), but omits that files are written to the local disk and that non-idempotency means repeated calls create additional files, which is a notable gap for a download tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the key constraint ('without overwriting') is stated early. It is efficient, though arguably too terse for a tool whose parameters and prerequisites are undocumented.

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 with 0% parameter coverage, no usage guidance, and an unstated prerequisite that run_id must reference a completed batch, the description is insufficient for an agent to invoke this correctly without external context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for two required parameters, so the burden is entirely on the description, which never explains what run_id identifies (a batch run id?) or that dest_dir is the target directory. 'New local files' is only a weak hint at dest_dir, leaving run_id completely undefined.

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 verb+resource ('Download completed snapshots') is specific enough to convey the operation, and 'completed' hints the source is a finished batch run. However, 'snapshots' is never defined and the description does not distinguish this from sibling tools like revit_model_snapshot or revit_batch_status, so an agent must guess what artifact is being fetched.

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 or when-not-to-use guidance and no named alternative among the many batch/snapshot siblings. The only implicit condition is that snapshots must be 'completed', which is not tied to any prerequisite (e.g. a run_id from a finished job).

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, idempotentHint=false). The description usefully adds that the run is 'persistent' and accepts local, UNC, or RSN model sources, which is real context beyond annotations, but says nothing about how to observe progress or retrieve results.

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 clean, front-loaded sentence with no filler. It is efficient, though the brevity comes at the cost of substance rather than being tightly packed.

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 for a 5-parameter start tool that begins an asynchronous polling workflow, the description omits what gets collected, how the five inputs shape the run, and how to track completion. Substantially under-specified for its complexity.

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 five parameters (paths, years, folder, recursive, parameter_rules) are undocumented in both schema and description. The single mention of 'local, UNC, or RSN models' only obliquely hints at paths and leaves years, folder, recursive, and parameter_rules completely opaque.

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 the verb (Start) and that it operates on local/UNC/RSN models, but 'a persistent, read-only run' never says what is being collected. It does not distinguish itself from the sibling revit_batch, revit_batch_fetch, or revit_batch_status, so an agent can't tell which batch tool to pick.

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 and no mention of alternatives. The async lifecycle siblings (revit_batch_status, revit_batch_fetch, revit_batch_cancel) exist but the description never says this is the entry point that must precede 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description usefully adds that the run state is durable and survives client exit. It does not explain why a pure status read carries idempotentHint=false, nor does it describe polling expectations or rate limits. Some added context, but the odd annotation is left unexplained.

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. The key qualifier (durable, post-exit) is placed immediately after the verb and resource.

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, and one parameter keeps the surface small. Still missing is the provenance/semantics of run_id and any statement of how this relates to revit_batch_start, revit_batch_fetch and revit_batch_cancel in a batch workflow.

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 single required run_id parameter is never mentioned in the description. An agent gets no hint that run_id comes from revit_batch_start or how it is formatted, so the description fails to 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?

States a specific verb (Read) and resource (durable run and model status), which is clearly distinct from revit_batch_start, revit_batch_cancel and revit_batch_fetch. It does not explicitly name those siblings or state the boundary between status polling and result fetching, so it stops 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?

"After the initiating client exits" gives a genuine timing condition for use, implying polling of a long-running batch. However, it never names the alternatives (revit_batch_fetch for results, revit_batch_cancel to abort, revit_jobs for job listings) or states when this is not the right call, so usage is only implied.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context that the operation is purely local and does not touch Revit, but says nothing about failure modes, snapshot format expectations, or how findings/previous_dir affect 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 zero filler; the source (snapshots) and the key constraint (no Revit contact) come first. Nothing is wasted.

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 annotations plus full schema coverage carry safety and parameter detail. The description is thin on the workflow relationship between snapshots_dir and previous_dir, but overall the structured fields fill the gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters, including the notable 'existing files are never replaced' constraint on output_path. The description adds no parameter-level meaning beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Build) and resource (local Excel report) plus a clear source (snapshots) and scope qualifier (without contacting Revit). The 'without contacting Revit' clause meaningfully separates it from the Revit-contacting siblings, though it does not name a specific alternative.

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 'without contacting Revit' implies an offline/post-hoc scenario, giving an implicit sense of when this tool applies. However, there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. use revit_model_snapshot first to create the snapshots).

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 non-idempotent, so the safety profile is known. The description adds meaningful process context beyond that: a confirmationText must be surfaced and an explicit approval step gates the retry with the token, which is valuable for a destructive operation.

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?

Two tight sentences with the operation stated first and the confirmation flow second. No redundant restatement of the name/title, though 'confirmationText' appears without definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be explained. But with 0% parameter description coverage and an unclear `save` flag (whether closing persists changes), the description leaves gaps for a destructive mutation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries full burden for four parameters. It only illuminates one (confirm_token, via the retry-with-token instruction) and leaves `save`, `document`, and `process_id` entirely unexplained 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 and resource ('Close a background document') that clearly distinguishes it from siblings like revit_open_document, revit_save_document, and revit_sync_document. The 'background document' scope adds useful precision, though it doesn't explain what a background document is.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a concrete workflow condition – only retry with the token after explicit chat approval – which is real usage guidance. However, it never states when to prefer closing vs. saving first, nor how it relates to sibling tools like save_document or sync_document.

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, idempotentHint and destructiveHint=false, so the safety profile is free. The description adds genuinely useful behavior beyond that: a geometric match does not create a monitor relationship or trigger Coordination Review warnings, and a non-empty 'skipped' means the answer is incomplete (with a 100-entry cap implication).

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 most important facts (compare action, no model change, monitor-relationship caveat) are front-loaded, and the paragraphs are dense with no filler. It is terse to the point of losing some needed detail, but nothing is wasted.

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 description does cover the key caveats (no mutation, monitor semantics, skipped/incompleteness). For a 12-parameter tool it still leaves most parameter behavior undocumented, which is a real 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?

With 12 parameters and only 33% schema coverage, the description should compensate heavily but does not. It says nothing about tolerance_mm, kinds, prefix/suffix, name_map, level_offset_mm or reuse_matching, leaving the majority of inputs ambiguous in both description and schema. It only reinforces the already-documented document-selection rule.

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 ('Compare') and resource ('host grids and levels') with scope ('one loaded Revit link'), which is clear enough to act on. It does not name the obvious sibling 'revit_align_link_datums', so the agent has to infer the read-only comparison vs. align distinction from the 'No model change is made' line rather than a direct routing cue.

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 provides a real conditional ('If more than one Revit instance is running, document is required; otherwise any instance may respond'), which is useful context. However, there is no explicit when-to-use vs. when-not guidance, and no contrast with the read/write sibling 'revit_align_link_datums' that an agent would weigh against 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 this a non-read-only, non-idempotent, destructive mutation, so the baseline is covered. The description adds genuinely useful behavior beyond that: dry_run executes then rolls back and returns the identical verification block, and an unknown/ambiguous document reference is rejected before any change.

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?

Three tight sentences, front-loaded with the core geometry and unit contract before the dry_run and document qualifications. Minimal waste, though the sentences are dense enough that the unit clause packs three facts into one line.

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 described, and the description covers the geometry contract, type fallback, dry-run verification, and document disambiguation. Missing only the failure behavior for invalid level names, which is a small residual gap for a 7-parameter 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?

Schema description coverage is only 14% (only `document` is documented in-schema), so the description must compensate and largely does: it clarifies the millimetre unit for start/end and height, that wall_type=null selects the first basic type, and dry_run's semantics. It does not spell out the level-name matching rule or endpoint ordering, leaving minor gaps.

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 and resource (create a straight wall) and pins down the scope: a named level, millimetre XY endpoints, height. It doesn't explicitly differentiate itself from siblings like revit_place_family or revit_move, but the operation 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?

It explains dry_run and when a document reference is required, which is real routing help, but never states when to reach for this tool versus the other modeling siblings in the catalog. Usage is implied rather than contrasted.

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 only declare the write/destructive/idempotency profile; the description goes well beyond them by disclosing that dependent elements are cascaded into the deletion, that the returned count includes those dependents, that dry_run still executes and rolls back to yield the same verification block, and that an ambiguous document reference is rejected before any change. These are exactly the consequence details an agent needs before invoking a destructive tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences, each carrying distinct information (cascade scope, dry-run semantics, document disambiguation), with the core destructive behavior front-loaded and 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?

For a destructive multi-parameter tool with an output schema present, the description covers consequences, verification, and document targeting adequately. Minor omissions remain: no mention of failure modes for already-deleted or locked elements, and no explicit ordering for multiple IDs.

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 only 33%, so the description must compensate for element_ids and dry_run, and it does: it clarifies that IDs are unitless and that dry_run rolls back rather than only simulating. The document semantics largely duplicate the schema's own description, so it is good compensation rather than full coverage.

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 ("Delete elements") and adds the important scope qualifier that Revit dependencies are removed with them. It is clearly distinguishable from read-only siblings like revit_query_elements or link-oriented removals such as revit_remove_links. It stops short of naming a sibling alternative explicitly, so 5 is not warranted.

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?

"when removal is intended" is a thin usage cue, and the dry_run sentence implies a verify-then-apply workflow without stating it as guidance (e.g., "use dry_run first to preview"). The document parameter's when-to-supply condition is genuinely useful, but there is no explicit when-not or alternative routing. Adequate but with clear gaps.

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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses failure semantics ('A missing active document, read failure or timeout raises an error; partial data is not returned'), empty-collection behavior, and result truncation ('Non-empty skipped means the answer is incomplete; skippedCount includes entries beyond the first 100'). These are genuinely useful traits not present in annotations or 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?

Front-loaded with the core purpose and return payload, then error and truncation notes, with no filler sentences. Slightly hurt by the detached trailing paragraph and a truncated-sounding clause about skippedCount that reads as an append rather than a clean statement.

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 read tool with an output schema, full annotation coverage, and 100% schema description coverage, this is nearly complete: purpose, targeting rules, failure modes and truncation are all covered. The one weak spot is the vaguely worded 'skipped' explanation, which an agent may still need to reconcile with the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all four parameters (document, process_id, timeout_seconds, pickup_timeout_seconds) are already fully documented in the schema, including precedence and default values. The description restates the document/instance rule but adds no new syntax or format detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read general information about the active Revit model') and enumerates the returned data (file name, Revit version, levels, area schemes, worksets, view count), which separates it from write-oriented siblings like revit_open_document. It does not, however, explicitly distinguish itself from closely related readers such as revit_documents or revit_model_snapshot.

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?

Gives clear context: it targets the active model, names the natural next step ('Call revit_list_views next for view analysis'), and states the instance-selection rule when multiple Revit instances are running. No explicit when-not-use or exclusions against sibling readers.

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 a safe read-only, idempotent, non-destructive profile, and the description layers on real operational detail: the returned field set, that an empty process returns [], that a non-empty skipped list means the answer is incomplete, and that skippedCount includes entries beyond the first 100 (an implicit result cap). This is meaningful behavior beyond structured fields.

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?

Two tight paragraphs with the core behavior and return shape front-loaded, followed by edge cases. Slightly dense and the field enumeration competes with the existing output schema, but no sentence is 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 exists, so the exhaustive field list is redundant, but the description covers the genuinely ambiguous cases an agent needs: empty results, multi-instance disambiguation, incomplete answers via skipped/skippedCount. Only environmental/permission prerequisites are left unstated.

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 80%, so most parameters are already documented. The description still adds semantics for include_linked (linked docs excluded unless set) and the multi-instance rule that makes document effectively required, going beyond the schema text.

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 ('List every open document in one Revit process, including background documents') with an explicit scope qualifier. It is distinguishable from siblings like revit_document_info and revit_open_document, though it never names them to sharpen the contrast.

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?

Gives conditional guidance: linked documents are excluded unless include_linked is set, and document is required when more than one Revit instance is running. It does not explicitly route the agent away from a specific sibling, but the conditions for correct invocation 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 destructiveHint=true and idempotentHint=false, but the description adds context beyond them: dry-run transactions roll back all changes, and the tool is refused in read-only mode. These are useful safety/permission disclosures the schema does not contain, though write-scope consequences beyond rollback are not detailed.

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?

Three short front-loaded statements with zero filler; the mode split and dry-run/read-only constraints come first. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a high-complexity mutation tool with 7 parameters, 14% schema coverage and four undiscriminated operation variants, the description is too thin. An output schema exists so return values need not be explained, but the operation vocabulary and error-handling parameters remain undocumented anywhere.

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 only 14%, so the description must carry parameter meaning. It explains families (exact names or ["*"]) and dry_run behavior, but says nothing about document, operations (the core op-discriminated purge/set_shared/remove_parameters/add_shared_parameters), stop_on_error, response_timeout_s, or overwrite_parameter_values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Edit) and resource (families) and distinguishes two modes: editing an open family in place versus named project families. It does not explicitly differentiate from nearby inspection siblings like revit_family_audit, but the mutation intent 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?

'In project mode, pass exact family names or ["*"]' and 'Refused in read-only mode' give real operational conditions for use. However, it never names alternatives (e.g. revit_set_parameter for instance values or revit_family_audit to inspect first), so the when-to-use-vs-siblings guidance is only implied.

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?

Beyond the readOnly/idempotent/non-destructive annotations, it discloses error behavior (absent element/document, read failure or timeout raises an error, partial data not returned), instance-selection rules when multiple Revit instances run, and skipped-list semantics including the 100-entry cap. This is unusually rich behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, but the description runs long with return-format details (room fields, mm rounding, parameter display/internal values) that an output schema already provides. Each sentence carries information, yet several are better suited to the output schema.

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, return values needn't be explained, and the description still adds units, error semantics, document/instance constraints, and skipped-list caveats. Nothing needed to invoke the tool correctly appears to be 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?

Schema description coverage is 100%, so the baseline is 3. The description's note that document is required with multiple instances largely restates what the schema already says, adding little new parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb and resource: 'Read parameters and geometry of an element by Revit ID.' This distinguishes it implicitly from search/list siblings, but it never names an alternative tool, 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?

The description explains conditional document requirements and suggests roomCenterMm for placement, but it never states when to choose this tool over siblings like revit_query_elements or revit_view_elements. No when-to-use vs when-not-to-use guidance is given.

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 non-idempotent, so safety is partly covered; the description adds genuinely new behavior: the artifact stays on the workstation (not returned/uploaded), it is refused in read-only mode, it needs the Navisworks exporter installed, and settings_xml supplies defaults while explicit arguments win. That last precedence rule is exactly the kind of context an agent cannot get from annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences, front-loaded with the operation and host, then preconditions, then output/precedence behavior. Every clause carries information; the only minor cost is the dense semicolon chain, which trades readability for brevity.

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, and the preconditions plus precedence rule cover the most important risks. However, for a 23-parameter mutation tool with near-zero schema coverage, the description leaves substantial gaps (overwrite behavior, timeout/dry_run semantics, interaction between element_ids and scope) that an agent would need to guess at.

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 4% across 23 parameters, so the description must carry the load, and it only clarifies settings_xml (exporter XML values) and the precedence relationship between settings_xml and explicit arguments. Nothing is said about scope, view, element_ids, overwrite, dry_run, response_timeout_s, or the many boolean export toggles, leaving most parameters semantically opaque.

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 ('Export NWC') plus the host context ('on the Revit workstation'), which is enough to separate it from read-oriented siblings like revit_nwc_settings_check or revit_export_view. It stops short of naming which sibling covers related pre-flight/settings work, so differentiation is inferred 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?

It gives real preconditions — 'Requires the Navisworks exporter; refused in read-only mode' — which tell the agent when the call will fail. But there is no explicit when-to-use-vs-alternative guidance, e.g. why call this instead of revit_nwc_settings_check first, or when revit_export_view is the better route.

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?

Beyond the readOnly/idempotent/non-destructive annotations, it discloses that the active view is not changed, lists the specific error conditions (missing document, unknown/unsupported view, existing destination, missing PNG, download failure), states timeout budgets and that timeouts produce no partial data, and explains skipped/skippedCount incompleteness.

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?

Purpose and output format are front-loaded, then behavior, errors, budgets and instance rules follow in a logical order. It is information-dense rather than padded, though the trailing skippedCount sentence reads as slightly bolted-on.

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, return values need not be re-explained, and the description still covers error modes, timeout behavior, multi-instance selection, and the non-mutation guarantee. Nothing an agent needs to invoke it correctly 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?

Schema coverage is 100%, so views, save_to, document, pixel_size and process_id are already fully documented, and the description largely restates them at a high level. It adds little syntax or constraint detail beyond the schema, making the baseline of 3 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?

States a specific verb (Export) plus resource (a selected view) plus output format (PNG), and the sibling set includes other exporters (revit_export_nwc) so the format distinction matters. An agent can tell this produces a raster image rather than an NWC or a data listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a use condition ("when numbers do not explain geometry") and concrete inspection targets (outlines, zones, room boundaries), plus the multi-instance rule for when document is required. It does not explicitly contrast with reader siblings like revit_view_summary or revit_show, but the context is clear.

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 readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavior beyond that: it does not save or load changes, multi-instance resolution rules, and importantly that a non-empty skipped set means an incomplete answer with skippedCount truncated past 100 entries.

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?

Front-loaded purpose followed by compact mode and multi-instance rules; every sentence carries operational weight. Formatting across blank lines is slightly ragged but no content is wasted.

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?

Output schema exists so return values need not be described, and the description still explains key return semantics (skipped/skippedCount). For a 4-param, zero-required, read-only audit tool whose annotations cover safety, this is nearly complete; only the untimed timeout parameter and truncation limit detail are 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?

With 50% schema coverage, two parameters lack schema descriptions. The description compensates meaningfully for families (exact names or ["*"], omit in family mode) and reinforces document's multi-instance requirement. It is silent on response_timeout_s and the maxItems=200 vs 'first 100' interaction, keeping it from a 5.

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 (Audit) and resource (families), plus distinguishes two modes (open family vs named project families). It does not name or contrast a sibling tool, but an agent can still tell it apart from edit-family or query tools by the read-only audit framing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells the agent how to invoke each mode: exact names or ["*"] in project mode, omit families in family mode, and use document when multiple Revit instances run. It gives operational context but does not name when to prefer this over sibling tools like revit_edit_families or revit_parameter_fill_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=false, idempotentHint=true, destructiveHint=false, so the safety bar is lower. The description usefully adds that the isolation is 'temporary' (reversible, does not mutate the model) and that a bad document reference is rejected before any change — genuine context beyond the annotations, though it does not say whether existing isolation is replaced or extended.

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?

Two sentences, front-loaded with the core action and scope, then the disambiguation rule. Little waste, though the stray line break and the reset/empty-list wording add slight parsing friction.

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, return values need not be described, and the annotations cover the mutation/reversibility profile. The description completes the picture for a view-state tool: what it affects, how to undo, and how to target a document. Only the add-vs-replace semantics of a second isolate call 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?

Schema coverage is only 33% (only `document` is documented), so the description must carry the rest. It does clarify that element_ids are unitless and that an empty list triggers reset, but the explicit `reset` boolean is never explained, and 'reset with an empty list' vs. the `reset` flag is potentially confusing. It compensates partially, not fully.

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 ('isolate IDs') plus scope ('active view') and a reversible mode ('reset with an empty list'), which separates it from neighbors like revit_select or revit_set_view_visibility. It never names a sibling explicitly, so an agent must infer the distinction, but the action 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?

Gives clear context ('for visual review'), the exact reset procedure ('reset with an empty list'), and the condition for the document argument ('when several are open'). It offers no explicit exclusions or named alternatives, but the when-to-use signal is solid.

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 explicitly states that supplying cancel_job_id will 'cancel one of this server process's own jobs,' which is a state-changing operation, while the annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. That is a direct conflict: an agent trusting the annotations would treat this as a pure read with no side effects. The otherwise useful disclosures (a running action finishes without interruption; non-empty 'skipped' means an incomplete answer; skippedCount caps at 100) cannot offset a contradiction of this severity.

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 text is compact and front-loads the core purpose before the optional cancel behavior and the multi-instance constraint. The trailing sentences about document selection and 'skipped'/'skippedCount' are appended without transition, reading more like stacked constraints than a structured narrative, but nothing is padded.

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, the description need not enumerate return fields, yet it still flags the important result-shape caveat (non-empty skipped = incomplete answer, skippedCount truncates past 100). Combined with the multi-instance document rule and cancel semantics, the coverage is solid; only the annotation mismatch and the absence of sibling routing keep it from being fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so the document and process_id semantics are already carried by the schema, and the description largely restates the multi-instance/documented requirement. It does add meaning the schema lacks for cancel_job_id (which has no schema description at all) by scoping it to 'this server process's own jobs,' clarifying a capability boundary rather than just a 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?

The description opens with a specific verb and resource: 'List queued and running jobs in the selected Revit process.' It is clearly a job-queue inspection tool, but it never distinguishes itself from lookalike siblings such as revit_batch_status or revit_batch_cancel, which also report on work items. An agent must infer the boundary between 'jobs' and 'batches'.

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 gives one conditional usage rule — supply cancel_job_id to cancel one of this server process's own jobs — and states that a document is required when more than one Revit instance is running. However, there is no guidance on when to prefer this tool over revit_batch_status or revit_list_instances, and no explicit statement of what it is not for.

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

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

Goes well beyond the readOnly/idempotent/destructive annotations by disclosing the 100-entry cap without pagination, that summary counts cover all entries, empty-list behavior, per-entry failures surfacing in error with status Other, error semantics for missing document/read failure/timeout, and that timeout partials are not returned. It also explains the skipped/skippedCount meaning, which is exactly the kind of behavioral detail an agent needs.

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?

Purpose is front-loaded in the first sentence, followed by well-organized output and error behavior paragraphs. It is dense and slightly long, with some clauses (e.g. 'timeout partials are not returned') that border on redundant, but nearly every sentence carries operational value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only status tool with four optional parameters and an output schema, the description covers output shape, caps, error/failure modes, and multi-instance routing. Despite the output schema existing, the added return-value context is genuinely useful rather than filler.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (document, process_id, timeout_seconds, pickup_timeout_seconds) are already fully documented, including precedence and timeout semantics. The description mentions the document requirement for multi-instance cases but adds no new parameter meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read RVT, CAD and image link status') and frames the scope around an export or hand-over workflow. It is clearly distinguishable from siblings such as revit_compare_link_datums, revit_remove_links and revit_align_link_datums, which mutate or compare rather than read status.

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?

Gives a clear usage context ('before an export or hand-over') and explains the preconditions for the read via the multi-instance/document rule. However, it never names a concrete alternative tool or an explicit when-not-to-use condition, so routing is inferred rather than 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?

Beyond the readOnly/idempotent/non-destructive annotations, it discloses error behavior (unknown section, missing document, read failure, timeout all raise), that no partial data is returned, and truncation semantics ('skippedCount includes entries beyond the first 100'; non-empty skipped means an incomplete answer). It also covers multi-instance routing. This is meaningful behavior the annotations cannot express.

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?

Purpose and return shape are front-loaded, and every sentence carries information (routing, error modes, truncation). It is dense rather than wasteful, though the run-on packing of routing/error/instance rules into a few long sentences slightly hurts scannability.

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, the description need not explain return fields, and it still supplies the operationally important extras: multi-instance/document requirement, error conditions, and truncation/incompleteness signals. Nothing critical for calling it correctly 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?

Schema coverage is 80%, and the description still adds value by enumerating the legal section values (categories, family-types, levels, area-schemes, views, worksets, phases, parameters) that the schema leaves as a bare string with no enum, and by explaining that the parameters section reports localized names/categories/value types. It goes modestly beyond the schema without restating the fully documented instance/timeout 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?

States a specific verb+resource ('List Catalog' / 'Discover valid model names') and enumerates exactly what the tool returns (section + items with names, IDs, categories, types, counts). It also differentiates itself from siblings revit_aggregate_elements and revit_query_elements, so an agent can pick it apart from neighbors without opening schemas.

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?

Gives explicit routing: 'Start universal queries here, then prefer revit_aggregate_elements for counts and breakdowns; use revit_query_elements only for individual rows.' That is a concrete when-to-use / when-to-use-something-else rule set, plus the prerequisite that section is required and the multi-instance document requirement.

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

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

With readOnly/idempotent annotations already covering safety, the description still adds substantial behavioral depth: what pluginResponding means under file channel v2, that busy/unresponsive processes stay listed with pluginResponding=false, mode-specific sourcing (local/SSH heartbeats with fallback vs HTTP single-process), and that transport failures raise errors. This is well beyond what annotations convey.

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?

Purpose and the returned field list are front-loaded, and most sentences carry distinct operational meaning. The closing sentence about skipped/skippedCount overlaps with the available output schema and is slightly redundant, but overall it is tight for the amount of behavior it must convey.

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 an output schema and rich annotations, yet the description still covers edge cases (empty results, unresponsive processes, incomplete answers via skipped) and mode differences, so an agent can call and interpret it confidently. A minor gap is that it re-explains return fields the output schema already defines.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single 'document' parameter is already fully documented in the schema, including substring matching and the exactly-one-match read rule. The description adds only marginal semantics (no matches returns instances=[]), so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb and resource ('List Revit processes and their active documents'), and the following sentences enumerate exactly what an instance record contains (documentName, processId, pluginResponding, etc.). This clearly separates it from document-scoped siblings like revit_documents or revit_document_info.

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?

'Use this tool before choosing a unique document substring for other tools' gives a concrete sequencing rule that positions it as the discovery step ahead of the document-scoped tools. It does not name specific alternatives or exclusions, but the when-to-use context is explicit and actionable.

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?

Beyond the readOnly/idempotent annotations, the description discloses the empty-result contract (elements=[]), the full failure surface (invalid relation, missing/wrong source, missing document, read failure, timeout), the no-partial-data guarantee, the 100-entry truncation with skipped/skippedCount, and the multi-instance document requirement. That is a rich behavioral profile annotations cannot supply.

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?

Front-loaded with purpose and return shape, then argument requirements, then error semantics and multi-instance caveats. Dense but each block earns its place; the multi-instance sentence mildly duplicates the document parameter description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter read tool with an output schema and annotations, the description covers the missing pieces: relation vocabulary, source argument pairing, failure modes, truncation semantics, and instance-selection rules. Nothing an agent needs to call it correctly is absent.

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 86%, so the schema already carries most parameter meaning. The description adds the one thing the schema cannot: the actual relation values and which of them pair with source_name versus source_id, plus the rule that document becomes mandatory when multiple Revit instances run. It repeats some schema text, keeping it out of 5 territory.

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 ('Read model object membership or dependencies') and enumerates the exact relation types it can resolve, so an agent knows this is a relation/membership traversal tool rather than a generic element query. It does not, however, explicitly differentiate itself from nearby siblings such as revit_query_elements, revit_view_elements or revit_aggregate_elements.

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?

Gives clear context for use by naming each relation and the source argument each requires, plus routing guidance ('Obtain source names from revit_list_catalog and IDs from element queries'). No explicit when-not-to-use or statement of which sibling to prefer for overlapping element data, so it stops short of a 5.

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 cover read-only/idempotent safety, and the description adds substantial operational detail beyond them: empty-filter behavior (views=[]), error-on-failure with no partial data, the multi-instance document requirement, and the meaning of skipped/skippedCount (incomplete results, entries capped at 100). This is exactly the kind of context annotations cannot express.

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 purpose and empty-result rule are front-loaded, and each sentence carries operational value (errors, skipped semantics, multi-instance rule). It is dense but not padded, with only minor structural noise from the stray blank line separating the instance note.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite an output schema existing, the description adds enough about result shape (id, name, type, level, scale, template plus counts), failure modes, and incompleteness signaling that an agent can call it and interpret edge cases correctly. Nothing material is missing for a read-only list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all six parameters, including the document-vs-instance and timeout semantics. The description mostly echoes those rules (document required for multiple instances, timeout raises) rather than adding new per-parameter meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (find/list non-template views) with an explicit scope qualifier and a stated downstream purpose ('before analyzing a view'). It references the sibling revit_view_summary and distinguishes itself from view-analysis tools by being the discovery step.

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?

Gives clear context and a workflow hand-off ('Use a returned name with revit_view_summary before requesting element pages'), which tells the agent when this tool fits. It does not explicitly contrast with revit_view_info or other view-listing siblings, so it stops short of full alternative 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?

Annotations already cover the read-only/idempotent/non-destructive profile, and the description adds substantial context beyond them: error behavior on missing document, read failure or timeout, the guarantee that partial data is never returned, the meaning of skipped/skippedCount (incompleteness, 100-entry truncation), and multi-instance routing 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?

Mostly dense and front-loaded, with the workflow instruction placed early. The trailing paragraph on multi-instance routing and skipped counts is separated by a blank line and reads as appended rather than integrated, which slightly hurts flow but every sentence carries real 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?

For a 6-parameter read tool with an output schema, the description covers everything an agent needs: filtering workflow, document resolution requirements, error conditions, partial-data guarantees, and truncation/skip semantics. Return-value detail is left to the output schema as expected.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: that warning_text should be fed back from a prior call and combined with include_elements=true to drill into one group, and that document is conditionally required. It stops short of documenting timeout/pickup semantics beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Group model warnings by description text'), which clearly identifies the operation and its grouping behavior. It does not explicitly name or contrast with the sibling revit_view_warnings, so an agent must infer the distinction, but the resource and output shape are 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?

It prescribes an explicit workflow: 'Start without filters, then repeat with a returned warning_text and include_elements=true to inspect one group.' It also states the prerequisite that document is required when multiple Revit instances are running, which is exactly the kind of when-to-use condition an agent needs.

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 well beyond the annotations: it discloses that absent objects report zero, unavailable metrics are null and surfaced in skipped entries, that missing document/read failure/timeout raise errors with no timeout partials, and that document is required when multiple instances run. This is exactly the behavioral context annotations alone would not convey.

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?

Front-loads the purpose in the first sentence, then layers return shape, error behavior, and multi-instance/skipped caveats. Mostly efficient, though the final paragraph packs several distinct caveats into a dense run-on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even with an output schema present, the description covers error conditions, partial-result semantics, skipped-count truncation, and multi-instance behavior, leaving no material gap for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all four parameters, including the document/process_id precedence and timeout semantics. The description adds only a marginal restatement of the multi-instance document requirement, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Read model quality counts') and enumerates the return contents (project metadata, file size, counts, unit settings, top warning groups). It differentiates from revit_list_warnings but does not distinguish itself from other read-oriented siblings like revit_model_snapshot or revit_document_info.

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?

Gives a clear usage context ('before an export or hand-over') and names an alternative with its condition ('Use revit_list_warnings to inspect affected elements'). No explicit when-not guidance, but the context for selection is clear.

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 establish readOnly/idempotent/non-destructive, and the description adds substantive behavioral caveats beyond them: warning groups cap at 200 element IDs, closed worksets can truncate results, a non-empty 'skipped' means the answer is incomplete, and skippedCount only reflects entries past the first 100. That is exactly the kind of incompleteness disclosure an auditing agent needs.

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 purpose is front-loaded in the first sentence and the remaining sentences are dense, caveat-bearing facts with no filler. The structure is a bit list-like and jumps between unrelated topics (parameter rules, warning caps, instance selection, skipped counts) without grouping, but nothing is wasted.

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, return values need no explanation, and the description still covers the key completeness signals (skipped/skippedCount), the instance-selection precondition, and result-truncation causes. For a 5-parameter audit tool this gives an agent everything needed to call it and interpret 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 coverage is already 80% (baseline 3), and the description goes further by explaining the one undocumented parameter: 'Each parameter rule pairs one category with one parameter.' It also restates the instance-resolution precondition for the omitted document/process_id case, adding meaning over the schema text.

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 ('Read a schema version 1 project snapshot') and scopes it to 'batch audits'. However, it does not differentiate itself from adjacent read tools such as revit_model_health or revit_document_info, so an agent still has to infer which aggregate view it wants.

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 batch audits' implies when the tool is appropriate, and it gives one real routing rule: document is required when more than one Revit instance is running. There is no explicit when-not guidance and no named alternative among the many sibling read 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 idempotentHint=false, and the description adds genuinely new behavior: dry_run executes then rolls back while returning the same verification block, and an unknown/ambiguous document reference is rejected before any change. It does not explain recoverability (e.g. whether revit_undo_last reverses a move) or limits on batch size.

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?

Three tight sentences, front-loaded with the core action and units before the dry_run and document caveats. The opening clause 'when adjusting their position' is mildly redundant with 'move', but nothing else is wasted.

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 re-explained, and annotations carry the safety profile. Combined with unit/axis semantics, dry_run behavior and document disambiguation, the definition is nearly complete; the gap is element_ids provenance and any statement about reversibility after a real move.

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 only 17%, so the description must carry the load and largely does: it defines dx_mm/dy_mm/dz_mm as millimetre offsets on model axes, explains dry_run's execute-and-rollback semantics, and clarifies document matching. Only element_ids (source/validity of the IDs) is left undocumented.

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 ('Move elements') and adds the scope of the operation plus the unit/axis convention for the offsets. No sibling is named or contrasted, but the operation itself is unique enough among the listed siblings (align, place, create, delete) that an agent can route to it.

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 'when adjusting their position' gives an implied trigger, and the document parameter guidance explains when to pass it. There is no explicit statement of when not to use this tool versus alternatives such as revit_align_link_datums or revit_place_family, so usage remains inferred.

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/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: a non-empty 'skipped' list means the answer is incomplete, and skippedCount can exceed the first 100 entries. That truncation disclosure is real value beyond the annotations, though it stops short of describing the result payload.

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?

Three tight sentences that front-load the core action, then the instance-selection rule, then the truncation caveat. No filler, though the second sentence is dense with multiple clauses packed into one line.

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. The description covers instance selection and the incomplete-answer signal, which are the key gotchas for correct invocation. Adequate for this complexity level.

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 80%, so the schema already documents document, process_id, timeout_seconds, and pickup_timeout_seconds in detail. The description only restates the multi-instance document requirement, adding little syntax or format meaning beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Parse') and resource ('Navisworks exporter XML file') with the scoping constraint 'on the Revit workstation without exporting,' which cleanly distinguishes it from the sibling revit_export_nwc by explicitly negating export. An agent can select it without opening either schema.

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?

Gives a concrete usage condition for the document parameter (required when more than one Revit instance is running) and the truncation caveat, but never states the high-level when-to-use case (e.g. verify settings before exporting) or exclusions versus revit_export_nwc. Usage is implied rather than prescribed.

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 idempotentHint=false. The description adds useful context (central models default to detached, cloud unsupported), but never explains the destructive nature, what state is affected, or why the operation is non-idempotent.

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?

Three tight sentences, front-loaded with the core action and path constraints. No wasted words, though the brevity comes at the cost of behavioral and parameter 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, non-idempotent tool with 6 undocumented parameters and zero schema coverage, this description is too thin. The output schema covers returns, but the destructive semantics and parameter behavior an agent needs before invoking it are 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?

Schema description coverage is 0% across 6 parameters, and the description only obliquely touches the 'mode' parameter via 'default to detached.' Parameters like audit, activate, worksets, and process_id carry no meaning in either the schema or the description, leaving the agent to guess.

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 (Open) and resource (local/UNC/RSN model), and scopes it with supported path types. It does not explicitly contrast with close/save siblings, but the open action is self-evident and distinct.

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?

'Cloud paths are unsupported' gives a clear when-not, and 'Central models default to detached' implies usage context. However, there is no explicit guidance on when to prefer a particular mode (e.g., read_only_local vs detached) or how this relates to sibling open/close 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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses non-obvious behavior: zero counts and empty samples for no matches, absent parameters counted as missing while numeric zero counts as filled, errors on missing document/invalid scope/timeout, no partial data returned, and the skipped/skippedCount truncation semantics. This is rich disclosure the annotations cannot provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then return shape, semantics, errors, and operational caveats in tight sentences. It is dense but each sentence carries distinct information; the return-shape sentence is slightly redundant given an output schema exists.

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 11-parameter read tool with an output schema, the description covers the remaining gaps: error conditions, edge-case counting semantics, truncation, and multi-instance document resolution. An agent has everything needed to invoke and interpret it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 73% and the schema already documents view, document, categories, parameters, sample_limit, and the timeout params in detail. The description adds only the multi-instance document requirement and the skipped-entries behavior, so it does not meaningfully exceed the baseline the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a precise verb and resource with scope and timing: 'Count filled, empty and missing parameters before an export or hand-over.' An agent can tell this apart from query-oriented siblings like revit_query_elements or revit_model_health by the fill-status framing, though no sibling is named 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?

It clearly states the intended context ('before an export or hand-over') and adds operational routing rules (document required when multiple instances run). It does not name alternatives or state when-not to use it, so it falls short of the explicit routing seen in the top tier.

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 establish readOnly, idempotent and non-destructive, so the bar is lower; the description still adds real behavior beyond them: it returns data='pong' even with no document, failures and timeouts raise errors with no partial result, and it warns that a non-empty 'skipped' means an incomplete answer. The skipped/skippedCount sentence is somewhat cryptic, which keeps this from a 5.

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 core purpose is front-loaded in the first sentence, and the multi-instance rule is placed clearly. The trailing sentence about 'skipped'/'skippedCount' and the 100-entry limit is terse and its relevance to a ping is unclear, so it dilutes rather than earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering the safety profile, the description only needs to add scope and failure semantics, which it does (pong response, error-on-failure, no partial results, multi-instance requirement). The ambiguous skipped/skippedCount note is the only notable gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (document, process_id, timeout_seconds, pickup_timeout_seconds) are already fully documented in the schema, making 3 the baseline. The description only reinforces the document-when-multiple-instances rule already present in the schema, adding no new parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Check the RevitModelMcp connection') and immediately scopes it against the rest of the family with 'without reading the model', which separates it from the many read-oriented siblings such as revit_document_info and revit_model_snapshot. An agent can select this as a pure connectivity probe without opening any schema.

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 states a clear usage condition: when more than one Revit instance is running, a document must be supplied; otherwise any instance may answer, and it works even with no active document. That is actionable context, but it never explicitly names an alternative (e.g. revit_list_instances) or says when not to use this 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 flag a non-read-only, non-idempotent, destructive operation; the description adds real behavioral detail beyond them — dry_run executes then rolls back and returns the same verification block, unknown/ambiguous document references are rejected before any change, and missing families return similar names with categories. It stops short of explaining what a placement disrupts or how existing geometry is affected.

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?

Front-loads the core operation in one sentence, then uses short paragraphs for name resolution, units, dry_run, and document disambiguation. Efficient overall, though the phantom roomCenterMm line is wasted/inaccurate content.

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, 5-required mutation tool with rich annotations and an output schema, the description covers the highest-risk semantics — naming/type resolution, units, dry-run rollback, and document targeting. It leaves level semantics and failure/rollback behavior for real (non-dry-run) placements unexplained, and the schema-absent roomCenterMm mention slightly undercuts completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With only 13% schema description coverage, the description carries the burden well: it documents family ('name' or 'Family: Type', case-insensitive), type_name null semantics and type-conflict rejection, XY units in millimetres, and rotation in degrees. However, it references 'roomCenterMm', a parameter that does not exist anywhere in the input schema, which could mislead an agent attempting that argument.

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 ('Place a loaded unhosted family on a named level') plus the purpose ('for layout'), which cleanly separates it from siblings like revit_move, revit_edit_families, and revit_list_instances. An agent can identify the operation without opening the schema.

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?

Gives concrete usage conditions: null type_name falls back to the embedded/first type, conflicting types are rejected, missing families return near-matches, dry_run rolls back, and document must be passed to disambiguate multiple open models. It does not, however, say when to prefer this over alternatives such as revit_batch or revit_move for positioning.

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 cover read-only/idempotent/non-destructive, and the description goes well beyond them: it discloses failure modes ("invalid fields or filters, a missing document, read failure or timeout raise errors"), guarantees no partial data, and describes multi-instance document requirements and skipped/skippedCount semantics. This is exactly the extra context an agent needs to invoke safely.

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?

Front-loads the core read/pagination contract in tight sentences, then back-loads secondary operational context (multi-instance handling, skipped counts). Every sentence carries information, though the density and the trailing multi-instance note are slightly heavy.

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 19-parameter, stateful query tool, the description covers prerequisites, pagination, units, error behavior, and document selection, and it still summarizes the return shape even though an output schema exists. Nothing an agent needs to call it correctly 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?

Schema coverage is 58%, so the schema documents many parameters, but the description adds cross-cutting semantics the schema lacks: a global unit convention (mm, m2, m3), the meaning of roomCenterMm versus a bounding-box centre, and the offset/hasMore pagination contract. It does not add meaning for the undocumented filters (level, phase, family, workset, categories), so it falls short of fully compensating.

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 ("Read a page of matching element rows") and anchors it to the workflow start ("after revit_list_catalog"). It explicitly differentiates from siblings by naming revit_list_catalog and revit_aggregate_elements, so an agent can tell it apart from the catalogue and aggregation 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?

Gives explicit sequencing ("Call revit_list_catalog first") and an alternative for a different need ("prefer revit_aggregate_elements for counts and breakdowns"). It also states the pagination loop condition ("advance offset while hasMore=true") and the termination case ("offset beyond the result return 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the agent knows this is an irreversible-feeling write. The description adds one genuinely useful trait beyond that — the dry_run preview path — but says nothing about reversibility, whether linked elements survive, or scope of deletion.

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 tight sentence with the destructive action front-loaded and the safety hint trailing. Nothing is padded, though for a five-parameter destructive tool the extreme terseness edges toward under-specification rather than economy.

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 tool with five parameters and only 20% schema coverage, the description omits the filter (kinds), the CAD-import flag, and the document-disambiguation requirement documented only in the schema. Output schema exists so return values need no explanation, but input-side completeness is clearly lacking.

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 only 20% (just the 'document' param), so the description carries the burden for the other four. 'Link types' loosely maps to kinds and 'instances' to links, but the accepted forms of links (names/IDs/'*'), the kinds enum, include_imported_cad, and document disambiguation are all unexplained in both places.

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: 'Delete selected link types and their instances.' This distinguishes it from revit_links_status (read) and the generic revit_delete. However, 'selected' is left undefined and the tool is not contrasted with revit_delete, which also removes model content.

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 only guidance is procedural: 'preview with dry_run,' which implies you should dry-run before committing. There is no statement of when to use this tool versus revit_delete, revit_links_status, or revit_compare_link_datums, and no prerequisites such as needing an open document.

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 idempotentHint=false, and the description adds a confirmation/approval workflow detail that goes beyond the annotations. It stops short of disclosing the real destructive risks implied by overwrite and save_as, so the value added is partial.

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, but it is not front-loaded with the tool's purpose and mixes a precondition with an oblique 'token retry' clause. The brevity here stems from under-specification rather than disciplined concision.

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 described, but for a destructive, non-idempotent save tool with 6 undocumented parameters and no annotation-level detail on data loss, the description is far too thin to guide 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% across 6 parameters, so the description carries the full burden of explaining document, save_as, overwrite, compact, process_id, and confirm_token. Its only indirect nod is the 'token'/'confirmationText' reference, which loosely maps to confirm_token; the other five parameters (notably overwrite and save_as) are entirely undocumented.

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 the verb 'save' but frames it entirely as a workflow precondition ('Save only after showing confirmationText...') rather than stating what the tool does — e.g., that it saves the active Revit document. It never clarifies the resource being saved or how it differs from siblings like revit_sync_document or revit_close_document.

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 does give one concrete when-to-use condition (only after showing confirmationText and receiving explicit chat approval), which is actionable. However, it offers no alternatives or when-not-to-use guidance, and the reference to a 'token retry' is unexplained, leaving the actual trigger condition ambiguous.

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, idempotentHint=true, destructiveHint=false, and the description is consistent with them. Beyond the annotations it adds real behavior: an empty list clears the selection, and an unknown or ambiguous document reference is rejected before any change occurs. It stops short of saying whether the selection persists or how it interacts with later tools.

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?

Two tight sentences, front-loaded with what the tool does, then the disambiguation rule. The only mild redundancy is re-stating the `document` guidance already carried in the schema; nothing else is wasted.

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, return values need no explanation, and the two-parameter surface is simple. The description covers clearing semantics, unitless IDs, and document disambiguation, leaving only the persistence/interaction of the selection with other tools unstated.

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 only 50%: `element_ids` has no schema description at all, and `document` is fully documented in the schema (the prose here largely restates it). The description compensates for the gap by explaining that IDs are unitless and that an empty list is a clear operation, which is genuine added meaning for the undocumented array parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first clause gives a specific verb and resource — select element IDs for inspection in Revit — and adds two scoping facts (empty list clears selection, IDs are unitless). It does not distinguish itself from related view-state siblings like revit_show or revit_isolate, so it is clear but not sibling-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?

It states one concrete usage rule (pass `document` when several models are open; omit when only one is) and the empty-list-clear convention. It never says when to prefer this over sibling tools that also affect what is displayed, so guidance is implied rather than explicit.

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 destructive=true and idempotent=true; the description adds real behavior beyond them, explaining that dry_run executes and rolls back, that ambiguous matches are refused with candidate details, and that ambiguous document references are rejected before any change. Missing only auth/permission notes, so a 4.

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?

Front-loaded with the core action, then parameter-selection, value typing, dry_run and document semantics in efficient order. Dense but each line earns its place; slightly long but not padded.

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 detailed, and the description still references the verification block returned by dry_run. It covers selection, typing, units, and document targeting well for a destructive mutation tool; only failure/permission behavior is thin.

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 only 17%, so the description carries the burden and largely does: it explains parameter_id vs parameter resolution, the value typing rules (JSON string/integer/number), the unit conventions (mm, m2, internal units), and the dry_run/document flags. Only element_id is left implicit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource and scope: 'Set exactly one instance or type parameter.' That clearly separates it from mutation siblings like revit_move or revit_delete. It doesn't name or route away from any sibling, but the purpose 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?

It gives concrete conditional guidance: use parameter_id to select by identifier vs a localized name when omitted, use dry_run to preview, and pass document only when multiple models are open. It stops short of explicit when-not-to-use or naming an alternative tool, so it's clear context rather than full 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=true, so the mutation/safety profile is covered structurally. The description adds useful context by noting dry_run provides a preview, but it does not explain what gets overwritten, how template_mode behaves, or permission/ambiguity handling.

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?

Two tight sentences with no filler; the core action is front-loaded and the format detail follows. Appropriately sized for the description's scope, though it could be argued the format sentence is the only real content beyond the verb.

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 10-parameter tool with 10% schema coverage the description is thin. It leaves most parameters and their interactions (template_mode, worksets, filters) undefined, which is insufficient 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 coverage is only 10% across 10 parameters, so the description carries a heavy compensation burden. It does clarify that category parameters accept Revit UI names, BuiltInCategory names (OST_StructuralColumns), English names or IDs, which is valuable, but the remaining parameters (worksets, template_mode, category_classes, filters, hide_categories_by_type) are entirely undocumented.

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 ('Change') and resource (category, workset and filter visibility in one view), making the tool's function immediately clear. It is distinguishable from read-oriented siblings like revit_view_info or revit_view_summary, though it does not explicitly name a sibling to differentiate against.

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?

Mentioning 'preview with dry_run' gives a concrete usage hint for safely checking changes before applying them. However, there is no explicit when-to-use vs when-not guidance, no mention of prerequisites (e.g. open document requirements), and no alternatives named.

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

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

Goes well beyond the readOnly/idempotent/non-destructive annotations: documents exact return shape (base/survey points, active site, project locations, link offsets in mm and rotations in degrees), the 100-item cap with total counts and no pagination, empty-list behavior, and error semantics (missing document, read failure, timeout raise errors; partial data never returned). It also explains the skipped/skippedCount incompleteness signal.

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?

Front-loaded with purpose, then return format, error behavior, and instance selection in a logical order. Dense but each sentence carries operational information; the stray paragraph break and minor overlap between the instance note and the document schema keep it from a 5.

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?

Covers timing, return units and rounding, pagination/cap limits, empty-result behavior, error and partial-data policy, and multi-instance resolution. With an output schema present it need not describe returns, yet its added behavioral detail leaves nothing an agent needs 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?

Schema description coverage is 100%, so the schema already documents all four parameters in depth, making 3 the baseline. The description restates the multi-instance rule for 'document' ('required; otherwise any instance may respond'), which largely duplicates what the schema already says rather than adding new semantic detail.

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 ('Read project and survey coordinates') and frames the moment it matters ('before an export or hand-over'). Reads are distinguishable from sibling coordinate/link tools such as revit_compare_link_datums and revit_align_link_datums, which compare or modify rather than read.

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?

Gives a clear usage context ('before an export or hand-over') and explains the instance-selection condition ('If more than one Revit instance is running, document is required'). It does not explicitly name alternative tools or state when not to use it, so it stops short of a 5.

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 readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description adds real behavioral context beyond them: it opens views, may suppress dialogs, and returns activeView/viewOpened/dialogsSuppressed. It also flags that unknown/ambiguous document references are rejected before any change, which is useful for a state-affecting tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences, front-loaded with the core action and view-opening behavior, followed by the document rule. It slightly duplicates the output schema by naming return fields, but there is little waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't enumerate returns (though it does), and it covers the key document-disambiguation precondition. The main remaining gap is the undocumented select/element_ids semantics against a low schema coverage.

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 only 33%, with select and element_ids undocumented in the schema. The description partially compensates by noting IDs are unitless and that select is optional, and by clarifying the document disambiguation rule, but it leaves the select semantics and ID format largely implicit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource ('Show elements') and adds scope detail ('optionally selecting them; open a level plan or 3D view when needed'). It is clear what the tool does, but it does not explicitly distinguish itself from close siblings like revit_select or revit_isolate, so an agent must infer the boundary.

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 gives contextual cues ('open a level plan or 3D view when needed', 'Pass document ... when several are open') but never states when to prefer this over revit_select, revit_isolate, or revit_view_elements. Usage is implied rather than specified.

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 idempotentHint=false, so the safety profile is partly covered. The description usefully adds that a two-step confirmation/token-retry flow exists, which explains the confirm_token parameter and the approval requirement. However, it never says what is actually destroyed or overwritten (local changes pushed to the central model, potential conflicts), which is the key behavioral fact for a destructive sync.

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 padding, which is good. But it is front-loaded with the conditional gate instead of the action, and the phrase 'for the token retry' is ambiguous without prior context about confirmationText.

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, non-idempotent 8-parameter operation with zero schema documentation, the description is far too thin. It does not describe the effect on the central model, conflict behavior, or the meaning of the relinquish/save-local options. An output schema exists, so return values need not be explained, but the preconditions and side effects are not covered.

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 and fails to meet it. It alludes to the confirm-token flow, but document, comment, compact, process_id, relinquish, save_local_before, and save_local_after get no explanation anywhere. An agent must guess at relinquish semantics and the save-local flags.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Synchronize only after...' which is a workflow gate rather than a statement of what the tool does. It never names the resource (the Revit document / central model) or explains what synchronizing means in this context, and it does nothing to distinguish itself from the sibling revit_save_document. The purpose is inferable only from the tool name.

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 states one explicit precondition: show confirmationText and receive explicit chat approval before retrying with a token. That is genuinely useful gating guidance, but there is no when-not guidance, no mention of alternatives such as revit_save_document, and no indication of the required document state (e.g. worksharing enabled).

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 idempotentHint=false, but the description goes well beyond them: it discloses the three guard conditions, the fact that failures return a 'clear refusal reason instead of running', and the ambiguity handling. That is exactly the kind of precondition/refusal behavior an agent needs before invoking a destructive tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core action, then preconditions, then the document disambiguation. Efficient and well ordered; the document sentence is mildly redundant with the schema but not wasteful.

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 comprehensive annotations, a 100%-covered single-parameter schema, and an output schema covering return values, the description supplies the remaining piece an agent needs: the preconditions under which the undo is permitted and what a refusal looks like. Nothing material 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?

Schema description coverage is 100%, so the parameter is fully documented in the schema (case-insensitive substring, required only when multiple documents are open, ambiguous refs rejected). The description's document sentence largely restates the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (undo) and resource (the last MCP action in Revit), and pins the scope further with 'through Revit's own undo command.' The 'last MCP action this session recorded' framing distinguishes it from any generic Revit undo, so an agent knows exactly what is being reversed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit eligibility conditions ('Allowed only when the target document is active, no command is pending... and Revit's last undo entry is still the one this session recorded') and the consequence when they fail. It does not name alternatives, but there is no competing undo/redo sibling, so the routing story is effectively complete.

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 readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the return shape, empty-result semantics, error conditions (missing document, unknown/unsupported view, read failure, timeout), the no-partial-data guarantee, and the skipped/skippedCount incompleteness signal. This is unusually thorough behavioral disclosure.

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?

Front-loaded with the core action and return shape, then routing, then failure/skipping behavior. Every sentence carries information, though the block is dense and the trailing instance/skip paragraph could be tightened.

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, yet the description still covers pagination, error surfaces, empty results, and incomplete-data signals for a complex 8-parameter read tool. Nothing an agent needs to call or interpret this tool 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?

Schema coverage is 63%, so the schema already documents view, document, process_id, and both timeouts. The description adds offset/limit pagination semantics and the multi-instance document rule, which the schema alone doesn't convey. The categories parameter remains undocumented in both places, so it stops short of 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.