Model MCP

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description should supply the operational detail. It adds only the 'already open' precondition; it does not say what happens if the title matches multiple documents, what error is returned when the document is not found, or how activation interacts with the host application state.

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, and the identifying qualification is placed immediately after the verb. It is efficient, though its brevity is part of why other dimensions are thin.

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

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

An output schema and annotations exist, so the description needn't explain return values or safety. For a two-parameter tool it is nearly adequate, but the undocumented `process_id` and the absence of any failure-mode context leave gaps for an agent calling it in a multi-document session.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. 'by title or path reference' usefully explains the accepted forms of the required `document` parameter, but the `process_id` parameter is left entirely unexplained in both the schema and the description.

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

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

The description states a specific verb ('Activate') and resource ('document'), and the qualifier 'already open' implicitly separates it from siblings like revit_open_document and revit_close_document. It stops short of naming those alternatives directly, so an agent must still infer the boundary from the surrounding tool list.

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?

'already open' implies the precondition under which this tool applies, which is useful routing context. However, no alternatives are named and no exclusions are stated, so the agent must infer that revit_open_document is the choice when the document is not yet open.

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 idempotentHint=false hints at UI-state side effects. The description adds useful behavior about zoom modes and the template-view restriction, but never explains what 'activate' does (make the view current in the UI), what happens if the view is a template, or why the call 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?

Two short sentences with the verb and the key modifier front-loaded; nothing is padded. The terseness is the issue rather than waste, since the second sentence packs three distinct zoom behaviors into a compressed list.

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 zoom modes are covered. But for a 6-parameter tool at 17% schema coverage, the description omits document targeting, view_type disambiguation, and what activate_document does, leaving real gaps 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 only 17%, so the description must carry the burden, yet it only explains the zoom parameter's three modes (fit / preserve zoom / frame element IDs). The required view parameter and document, view_type, process_id, and activate_document are all left to an undocumented schema.

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

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

"Activate a non-template view" gives a specific verb plus resource and adds a real constraint (template views are excluded), which distinguishes it from revit_activate_document and revit_close_views. It doesn't name those siblings explicitly, so an agent still has to infer the split.

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

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

No when-to-use or when-not-to-use guidance beyond the implicit 'non-template' scope. With siblings like revit_activate_document, revit_open_document, and revit_view_info in the list, the description should say which situation selects 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: unit conventions (mm, m2, m3) for summed values and the meaning of the response fields 'skipped' (incomplete) and 'skippedCount' (total skipped), which tells the agent how to interpret partial 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?

Four sentences, front-loaded with the core operation, then units, then the area-totals recipe, then output caveats. Dense and largely waste-free, though the unit sentence duplicates what the sum_field schema description already says.

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 shape needn't be explained, and the description still usefully clarifies the skipped/skippedCount semantics and unit conventions. For a 14-parameter read-only tool the coverage is solid, with the main gap being routing guidance against sibling query/schedule tools and behavior of the AND-combined parameter_filters.

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 64%, so roughly a third of parameters (level, phase, family, workset, categories) are undocumented in both places. The description adds meaning for sum_field units and clarifies that group_by takes one or two distinct fields, but it does not compensate for the undocumented filter parameters or explain interaction between parameter_filters and the scalar filters.

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 output form ('summarize matching elements by one or two fields, with optional sum and average'), which is clearly a grouping/aggregation operation. It does not name or distinguish from close siblings like revit_query_elements or revit_schedule_data, so an agent cannot tell from the text alone when aggregation beats a plain query.

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?

'For area totals, group by level and select the area scheme' gives one concrete conditional recipe, which is useful. Beyond that, usage is only implied: there is no statement of when to prefer this over revit_query_elements or revit_schedule_data, and no exclusion criteria.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the mutation and non-idempotent nature is known. The description adds two genuinely new facts beyond the annotations: an optional creation step and a rollback preview, plus the monitor-relationship exclusion. It says nothing about what is destroyed or undone, which is thin for a 17-param 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?

Two tightly written sentences, with the core action front-loaded and the scope caveat last. No filler, though the brevity is arguably wrong for a tool of this complexity (a completeness issue, not a conciseness one).

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, 17-parameter mutation tool with 6% schema coverage, the description leaves most parameters and most behavioral risk unexplained. An output schema exists so return values need not be described, but the parameter and safety picture is largely 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 only 6% (just the 'document' parameter is documented), so nearly all 16 remaining parameters carry no meaning in either the schema or the description. The description merely implies 'optional creation' (create_missing) and 'rollback preview' (dry_run) without mapping them to parameters, leaving the burden unmet.

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: aligning host grids and levels to a loaded link. It is distinguishable from the sibling revit_compare_link_datums by the verb 'align' versus 'compare', though it never names that sibling 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?

'with optional creation and rollback preview' implies the dry-run path, and 'Does not create a monitor relationship' is a useful scope boundary. However, no alternative tool is named and no when-to-use trigger (e.g. prefer compare first, or when a monitor is desired) is given, 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 safety is covered. The description adds real behavioral context beyond that: results reflect only the running Revit's API version, XML summaries may be absent, and 'skipped means incomplete; skippedCount is the total skipped' warns about partial 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?

Five short sentences, front-loaded with purpose then usage trigger then caveats. It is telegraphic in places ('skipped means incomplete') but every sentence carries information and none 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 return values need not be explained, and the description usefully flags partial-result semantics. However, for an 8-parameter tool with 38% schema coverage, the meaning of the enum and the three undocumented boolean/integer parameters is left entirely implicit.

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 38% across 8 parameters, so the description must compensate and largely does not. It never explains the 'kind' enum values (type/member/search), what 'limit' caps, what 'include_obsolete' or 'include_inherited' change, or how 'query' is matched.

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 ('Look up public Revit API types and members') and scopes it to reflection over the Revit API. It is clearly distinguishable from all sibling tools, which are document/model mutation or query tools rather than API documentation lookup.

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 an explicit usage trigger: 'The agent calls this before writing C# for an unfamiliar type.' That tells the agent when to reach for it. It does not name exclusions or an alternative tool, but no sibling covers API metadata, so the practical ambiguity is low.

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, so the safety profile is covered. The description adds only batch scope ('one or more views') and does not disclose what gets overwritten, whether changes are reversible, how dry_run behaves, or whether the operation requires an active document.

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 single sentence is front-loaded and free of waste, but it is arguably too terse for a destructive four-parameter tool with low schema coverage. It reads as under-specification rather than deliberate conciseness.

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

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

An output schema exists, so return values need not be described. However, for a destructive mutation with a dry_run option, document scoping, and only 25% schema description coverage, the description omits critical context needed to invoke the tool safely and 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 25%, with only the 'document' parameter documented. The description does not explain the 'views', 'template', or 'dry_run' parameters, their formats, or required matching behavior, so it 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 and resource: apply a view template to one or more views. Clear enough to distinguish from sibling view operations like revit_set_view_visibility or revit_activate_view, but it does not explicitly name alternatives or scope limitations.

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

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

Provides no guidance on when to use this tool versus alternatives, prerequisites, or when not to use it. The agent must infer usage entirely from the name and schema.

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 and destructiveHint=false but say nothing about paths or overwrite policy. The description adds two genuinely useful behavioral facts: paths resolve on the server machine (not the client), and existing files are refused rather than overwritten. That refusal behavior is non-obvious and directly affects invocation safety, though the description stops short of stating what a successful call returns or where the paths must point.

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, each carrying distinct information: what is written, where paths resolve, and the overwrite policy. Front-loaded with the action and resource, no filler or repetition.

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

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

An output schema covers return values and annotations cover the mutation profile, so the description only needs to supply the path and overwrite semantics it does supply. Minor omissions remain, such as the format default and whether the output directory must already exist, but the definition is sufficient to call the tool correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning and it only partially does: 'audit JSON file' maps to the audit parameter and 'paths resolve on the server machine' adds real meaning for output. The format parameter and its enum/default ('both') are only obliquely referenced via 'XLSX and HTML', and it is unclear whether output is a file path or a directory.

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

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

The description uses a specific verb ('Write') with concrete resources ('new XLSX and self-contained HTML reports') and names the input source ('local audit JSON file'). However, it does not distinguish itself from the near-identical sibling revit_build_report, leaving the agent unable to choose between them from the text alone.

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

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

Usage is only weakly implied by 'from a local audit JSON file' — the agent can infer a JSON input must exist first, but there is no explicit when-to-use, no when-not-to-use, and no mention of the obvious alternative revit_build_report. For a tool with such a close sibling, this is a meaningful gap.

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 annotations' mutation and safety hints, the description adds that cancellation is persisted and that unstarted models will be prevented from running. It leaves important scope questions unresolved, including what happens to models already running and whether a completed or previously cancelled run can be cancelled again.

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 single sentence is compact, front-loaded, and contains no filler. However, the compressed phrase 'Persist cancellation' is less immediately intelligible than a direct statement about saving the batch's cancelled state.

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 essential action and pending-model scope are present, and the output schema removes the need to document return values here. For reliable invocation, though, the definition still needs run_id provenance and clearer lifecycle and sibling-tool 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?

With 0% schema description coverage, the description needed to compensate for the sole run_id parameter but never mentions it. Its purpose as a batch-run identifier is inferable from the name, yet its source, expected format, and validity requirements remain 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?

Together with the title, the description clearly conveys cancelling a batch collection and specifically preventing its unstarted models from running. It does not explicitly differentiate this batch-level operation from the sibling revit_cancel_job.

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 reference to unstarted models implies when cancellation is useful, but there is no explicit when-to-use guidance or prerequisite workflow. In particular, it does not direct agents to revit_batch_start for obtaining a run, revit_batch_status for inspection, or revit_cancel_job for a different cancellation scope.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the agent knows this writes files safely and is not idempotent. The description adds concrete file-level behavior: it downloads to new local files and does not overwrite existing ones, which goes beyond the 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?

The description is a single front-loaded sentence with no wasted words and clear phrasing. It is concise, though slightly under-specified given the tool's two undocumented parameters.

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 two required parameters with no schema descriptions and no output schema explanation needed (since an output schema exists). The description covers file safety but omits what run_id identifies, what output_dir is for, and any batch-completion prerequisite, making it incomplete for correct invocation.

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

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

Schema description coverage is 0%, so the description must explain the two required parameters. It only vaguely hints at output_dir through 'new local files' and says nothing about run_id, leaving the meaning of both parameters largely 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 description states a specific verb ('Download') and resource ('completed snapshots'), and adds a scope ('to new local files without overwriting'). It distinguishes itself from sibling batch tools like revit_batch_status by focusing on fetching results, but it does not explicitly name alternatives.

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

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

The phrase 'completed snapshots' implies it should be used after a batch has finished, which is some usage guidance. However, it never states when to use this tool versus revit_batch_status, revit_batch_start, or other siblings, and gives no prerequisites or exclusions.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, and the description adds useful context: the run is 'persistent' (state is created, explaining the non-read-only annotation) and 'read-only' over the models themselves, plus the accepted model sources (local, UNC, RSN). However, it never says the run is asynchronous or that progress/results must be retrieved via revit_batch_status and revit_batch_fetch, which is the critical behavioral fact for a 'start' tool. There is mild tension between 'read-only run' and readOnlyHint=false, though it is reconcilable as read-only over the models while creating persistent job state.

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, no filler, and the core capability is front-loaded before the parameter note. The brevity is efficient but borders on under-specification given six undocumented parameters.

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 six-parameter, zero-coverage, job-initiating tool with an output schema, the description is far too thin: it omits how models are selected (paths vs folder vs years), what recursive and parameter_rules do, and that the returned run must be polled. The output schema means return values need not be described, but the invocation semantics and async workflow 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 six parameters, and the description explains only open_timeout_minutes, giving its default and the conditional 45-minute default when upgrading in memory — a genuinely useful detail. The other five parameters (paths, years, folder, recursive, parameter_rules) are left entirely undefined in both schema and description, including the key question of whether paths, folder, or years is the required input selector. The description therefore compensates for only one sixth of 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?

The description states a specific verb and resource — 'Start a persistent, read-only run over local, UNC or RSN models' — so an agent knows this initiates a batch collection job rather than reporting on one. The word 'Start' implicitly separates it from the revit_batch_status / revit_batch_cancel / revit_batch_fetch siblings, but those siblings are never named, so the differentiation is left to inference.

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

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

There is no statement of when to use this tool versus alternatives such as revit_process_models, nor any mention of the companion lifecycle tools (revit_batch_status, revit_batch_fetch, revit_batch_cancel) that an agent must call after starting a run. The word 'Start' hints at a lifecycle but no condition, prerequisite, or exclusion 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating the status is durable and remains readable after the initiating client exits. It does not add further detail about what "run status" or "model status" includes, though the output schema may cover return values.

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

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

The description is a single, front-loaded sentence with no wasted wording. It clearly leads with the action and resource before adding the timing condition.

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

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

The tool has annotations, an output schema, and only one parameter, which lowers the description burden. Still, for a batch-status tool the description should ideally clarify how run_id is obtained and how this differs from revit_batch_fetch or revit_jobs. It is minimally adequate but leaves those routing and parameter-origin gaps.

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

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

Schema description coverage is 0% and the single required parameter run_id is undocumented in the schema. The description does not mention run_id at all, nor does it explain where to obtain it (for example, from revit_batch_start). With low schema coverage, this is a clear gap.

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

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

The description states a specific verb and resource: "Read durable run and model status." It is more specific than the tool name alone and distinguishes itself from batch actions like start/cancel by focusing on status. It does not explicitly name the sibling alternatives such as revit_batch_fetch or revit_jobs, 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 phrase "after the initiating client exits" gives a clear timing/context signal for when to use the tool. However, it does not explicitly say when to use this instead of revit_batch_fetch, revit_jobs, or other status-like siblings, nor does it provide exclusions.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is partly covered. The description adds genuinely useful context that the operation is fully local and requires no live Revit connection, but it does not disclose that the run writes a file to the server filesystem or that the output is refused if the path exists (that detail lives only in the schema).

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

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

A single tight sentence with no filler, and the offline constraint is front-loaded where it matters most. It is arguably too compressed given the tool builds a multi-sheet report, but nothing is redundant.

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 full schema description coverage, the description only needs to establish purpose and the no-Revit behavioral stance, and it does both. Nothing an agent needs in order to call this correctly is missing from the combined description-plus-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 description coverage is 100%, so all four parameters (snapshots_dir, output_path, findings, previous_dir) are already documented in the schema. The description adds no further meaning about snapshot schema version, findings structure, or how previous_dir matching works, 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 and resource ('Build a local Excel report from snapshots') and adds a differentiator ('without contacting Revit') that separates it from Revit-touching siblings like revit_export or revit_audit_report. It stops short of naming which sibling produces snapshots (e.g. revit_model_snapshot) as the input source.

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

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

Usage is implied: use it when you already have snapshots on disk and want an offline Excel artifact. There is no explicit when-not, no prerequisite statement about obtaining snapshots first, and no mention that previous_dir enables a Changes comparison, so the agent must infer the workflow.

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 exactly which phases stop ('process-models stops before the next model'), what state unstarted models end in ('marked cancelled'), the non-interruptible boundary ('a single running Revit operation finishes'), and the durability guarantee ('completed changes stay committed'). This is the operational detail needed when the destructiveHint alone would be ambiguous.

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, the imperative action front-loaded and the three behavioral consequences packed into one semicolon-separated clause. No filler, no restatement of the title.

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 behavioral narrative plus destructive/idempotency annotations cover the safety profile well. The remaining gap is parameter meaning (process_id, document) and routing against revit_batch_cancel, which leaves the definition slightly short of fully self-sufficient.

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 the optional 'document' parameter carries a description, and 'job_id' and 'process_id' are bare. The description gives a clue that job_id identifies an 'action job' but says nothing about process_id's role or how document interacts with a job cancellation, leaving most parameters undocumented 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+resource: 'Request cancellation of an action jobId', which is precise about what is cancelled. However, it never distinguishes itself from the close sibling revit_batch_cancel (nor revit_process_models / revit_run_actions), so an agent cannot tell the two cancellation entry points apart from the description alone.

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

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

Usage is only implied: the description explains what happens when cancellation is requested, which helps an agent judge the consequences, but it names no condition for choosing this tool over revit_batch_cancel or waiting for revit_batch_status/revit_jobs. No when-not 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 declare readOnlyHint=false and destructiveHint=false, but the description adds real value beyond them: the temporary view is rolled back (cleanup behavior), the element cap of 500, and the meaning of 'skipped'/'skippedCount' in results. With no output schema, that return-value explanation is especially useful. It still omits what the response contains besides the PNG path.

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?

Four short sentences, front-loaded with the core action and the key constraint. 'skipped means incomplete; skippedCount is the total skipped' is terse to the point of being slightly cryptic, 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?

For a 7-parameter rendering tool with no output schema, the description covers the essential action, limits, transport modes, and cleanup behavior. It leaves gaps around the image framing (padding_mm), and what the call returns beyond localPath, which would matter for an agent assembling evidence.

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 57%, and several parameters (mode, element_ids, padding_mm) carry no schema description at all. The description partly compensates by naming the two mode values ('3d or plan') and the 1-to-500 element range, but adds nothing about padding_mm or how element_ids should be sourced. Baseline 3 is appropriate at this coverage level.

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 — 'Render a highlighted PNG that marks 1 to 500 elements, for issue evidence' — which clearly separates it from read-only siblings like revit_show or revit_isolate. It does not name the closest alternative (revit_export_view), so the differentiation is implicit rather than explicit.

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

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

The phrase 'for issue evidence' and the 1-to-500 element bound imply when the tool fits, and 'The temporary view is rolled back' hints it is non-destructive. However, there is no explicit statement of when to prefer this over revit_export_view, revit_show, or revit_isolate, and no prerequisites for SSH vs local transport are 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?

Adds real behavior beyond the annotations: how duplicate type names are resolved via 'family', that dry_run rolls back, that group members land in skipped.inGroup, and that the call is refused if all elements are group members. Annotations only supply the generic destructive/not-idempotent flags; the description supplies the actual mutation semantics.

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 tightly packed sentences with the core action front-loaded and no filler. Density is high; 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 restated, and the description still flags the skipped.inGroup behavior. The main gap is that it never defines what makes a type 'compatible' or what happens on partial failure mid-batch.

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 20%, so the description must compensate. It explains 'family' (duplicate-name disambiguation) and 'dry_run' (rollback), but says nothing about 'element_ids' semantics, the 'type_name' matching rules, or the 'document' disambiguation parameter. Partial compensation only.

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

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

Specific verb+resource+scope: 'Change each element to one compatible type', which distinguishes it from parameter-editing siblings like revit_set_parameter or revit_update_parameters. It does not name an explicit alternative, 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?

Gives useful operating conditions (dry_run rolls back, group-member refusal) but never states when to choose this tool over siblings such as revit_set_parameter or revit_load_family. Usage is implied by the mutation scope rather than spelled out.

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 covered. The description adds genuine context beyond that: a two-call confirmation pattern where the first call 'changes nothing'. It still doesn't disclose what happens to unsaved changes or whether the save parameter triggers a commit.

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 zero filler, purpose front-loaded ahead of the confirmation requirement. The phrasing 'which changes nothing' is slightly ambiguous but the structure is efficient.

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 confirm-token flow is covered. However, for a destructive mutation with 0% parameter documentation, the description omits what 'save' does and the consequence of closing with unsaved work.

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

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

Schema coverage is 0% across 4 parameters, so the description must carry the load. It only explains confirm_token, leaving save, document, and process_id undocumented in both schema and description — roughly one of four parameters covered.

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 ('Close a background document'), and the 'background' qualifier narrows scope meaningfully against siblings like revit_open_document and revit_save_document. It stops short of explicitly naming which sibling it contrasts with, 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?

Implies a required two-step flow ('Needs confirm_token from a first call'), which tells the agent how to invoke it, but gives no explicit when-to-use vs. alternatives such as revit_save_document or revit_close_views. The invocation prerequisite is useful but not full usage guidance.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false, so safety is nominally covered. But the description adds nothing about the behavior that actually matters here: whether omitting 'views' closes all views, whether the active view can be closed, or whether unsaved view state is lost. The only hint at such behavior lives in an undocumented parameter name.

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 or redundancy. It is appropriately tight, though the brevity comes at the cost of the substance penalized in other dimensions rather than from good editing.

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

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

The output schema exists, so return values need not be described, but nothing about the three optional parameters or the all-views default is covered. For a tool whose entire behavior depends on optional arguments, one sentence is not sufficient context for correct invocation.

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

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

Schema description coverage is 0% across three parameters, and the description mentions none of them. 'views', 'process_id', and 'keep_active' (defaulting to true, which strongly implies it prevents closing the active view) are entirely unexplained, so the agent gets no help resolving name lists, process scoping, or the keep-active semantics.

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

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

"Close open UI views in the active document" gives a specific verb (close) and resource (UI views) plus a scope qualifier (active document). It does not distinguish itself from siblings such as revit_close_document, revit_activate_view, or revit_list_views, so an agent must infer the boundary itself.

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

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

There is no guidance on when to call this versus revit_close_document or revit_activate_view, no prerequisites, and no mention of what happens when the views parameter is omitted. The agent is left to infer whether a call with no arguments closes every open view or does nothing.

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, and "Changes nothing" merely restates that rather than adding new behavioral context. The one additive element is the note that "skipped means incomplete; skippedCount is the total skipped," but that is return-value semantics already covered by the existing output schema.

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

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

Three short sentences, front-loaded with the core action and free of filler. The final fragment ("skipped means incomplete; skippedCount is the total skipped") is telegraphic and would benefit from a clearer referent, 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?

For an 11-parameter tool with 27% schema coverage and no parameter hints, the description is far too thin — an agent cannot reasonably choose values for kinds, prefix/suffix, name_map, tolerance or level offset. The output schema lightens the burden on return values, but the input side remains largely undocumented.

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 27% across 11 parameters, and the description explains none of the undocumented ones: kinds, prefix, suffix, name_map, tolerance_mm, reuse_matching, and level_offset_mm are left with no guidance. Only link and the two documented document/process_id/timeout parameters have any semantics, so the description does not compensate for the coverage gap.

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

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

"Compare host grids and levels with one loaded Revit link" names a specific verb (compare) and specific resources (grids, levels), and "Changes nothing" implicitly contrasts it with the mutating sibling revit_align_link_datums. It stops short of explicitly naming that alternative, 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?

The phrase "one loaded Revit link" implies a prerequisite (a single link must already be loaded) and the compare/align distinction is implied by "Changes nothing." There is no explicit when-to-use/when-not statement and no reference to revit_align_link_datums, which is the obvious alternative.

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, so the safety profile is covered, and the description adds real value beyond them: dry_run performs a rollback, group members surface in skipped.inGroup, and the call is refused when every element is a group member. These are concrete post-conditions an agent cannot derive from 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?

Three dense sentences, no filler, with the core copy behavior front-loaded and the edge-case handling (dry_run, group refusal) trailing. Every sentence carries distinct actionable information.

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

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

An output schema exists so return-shape explanation is unnecessary, and the description covers the mutation's key side effects well. However, with three required parameters and low schema coverage, an agent still lacks clarity on element_ids selection, the document target, and dz handling, so it is only minimally complete for a destructive batch operation.

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

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

Schema description coverage is only 14%, so the description carries most of the load. It usefully clarifies the count range (1-100), the mm offset/multiple behavior, and dry_run rollback semantics, but element_ids, dz_mm, and the document selector remain unexplained in both places, leaving meaningful gaps for a 7-parameter tool.

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

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

States a specific verb+resource ('Create 1 to 100 successive copies') with the offset semantics front-loaded, so an agent immediately knows this produces duplicated geometry along an axis. It does not explicitly distinguish itself from neighbors like revit_move or revit_mirror, which also reposition geometry, so selection still requires inference.

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 how the tool behaves but never states when to prefer it over alternatives such as revit_move or revit_mirror, nor any prerequisites for choosing it. The only contextual cue is the group-member refusal, which is a constraint rather than when-to-use guidance.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so safety is covered. The description adds genuine behavioral context beyond that: how a missing Z is resolved (level elevation + kind's default offset) and how failed elbows surface as unjoined pairs. It omits the dry_run preview behavior, which is a relevant behavioral trait for a mutating tool.

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

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

Three tight sentences: action first, then two behavioral notes. No filler, and the core purpose is front-loaded before the edge-case details.

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

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

An output schema exists, so return values need not be explained, but for a 12-parameter destructive creation tool the definition is thin. It never clarifies the width/height vs diameter split by kind, how connect_to behaves, or what dry_run does, leaving substantial 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 only 8% (one of twelve params), so the description must carry the load but does not. It explains points_mm Z handling and the offset default, yet leaves width_mm, height_mm, diameter_mm, system_type, type_name, connect_to and dry_run entirely undefined in both schema and prose.

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 ('Create') plus the exact resource ('connected duct, pipe, cable tray or conduit segments'), and the four-kind enumeration maps directly to the kind enum. It is clearly distinguishable from siblings like revit_create_wall 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?

The description implies usage (build MEP runs from model points) but never states when to use this tool versus alternatives such as revit_create_wall or a generic run/action tool, and gives no prerequisites or exclusions. Context is inferable from the name but not spelled out.

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

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

Annotations already flag this as a non-read-only, destructive, non-idempotent operation, and the description is consistent with that. It adds genuinely useful behavioral context beyond the annotations: 'dry_run rolls back', 'itemized=false collapses identical rows', 'unknown names are listed in skipped', and the implicit unit system (mm, m2, m3).

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 dense but waste-free paragraph, front-loading the purpose before parameter behavior details. Semicolon-packed clauses make it slightly run-on, but every sentence carries information the agent needs.

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

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

For an 8-parameter mutation with an output schema (so return format needn't be re-explained), the description covers the key behavioral facets — ordering, filters, sorting/grouping, units, itemized collapsing, dry_run rollback, and skipped names. Minor gaps around 'name' and 'category' semantics keep it short of complete.

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

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

Schema description coverage is only 13% (just 'document'), so the description must carry the load, and it largely does: it explains fields (ordered, Revit UI names like Mark/Level/Count), filters (field/operator/value row selection), sort (ordering plus header/footer grouping), itemized=false collapsing, and dry_run rollback. Only 'name' and 'category' are left implicit, so this meaningfully compensates for the sparse schema.

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

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

The description opens with a specific verb and resource — 'Create a schedule for one category' — and clarifies the field ordering and naming convention. This clearly separates it from read-oriented siblings like revit_schedule_data and from other creation tools such as revit_create_view.

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

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

Usage is implied by the phrasing (create a schedule from a category and fields), but there is no explicit statement of when to prefer this over revit_schedule_data or other creation tools, and no prerequisites or exclusions are given. Adequate context, but the agent must infer the trigger conditions.

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 agent knows this mutates the model. The description adds genuine context beyond that by disclosing the default title-block selection behavior. However it says nothing about the dry_run preview path, undo/irreversibility, or duplicate sheet-number handling, so it remains thin for a mutation tool.

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

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

A single front-loaded sentence with no filler, and the title-block default is stated where it matters. It is efficient, though arguably too terse given the undocumented parameters.

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 destructive document-mutating tool the definition omits the dry_run preview contract, sheet number/name constraints, and any note that the sheet is added to the currently active document.

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

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

Schema description coverage is only 20% (only 'document' is documented), so the description must compensate. It partially covers title_block by describing the named-vs-first-loaded default, but 'name', 'number' and especially 'dry_run' receive no explanation of format, uniqueness, or preview semantics.

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

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

States a specific verb+resource ('Create a sheet') and adds the meaningful scope detail that it uses the first loaded or a named title block. It does not explicitly distinguish itself from near neighbors such as revit_place_views_on_sheet or revit_create_view, 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?

No when-to-use, when-not-to-use, or alternative is given. There is no mention of prerequisites such as an active/open document, nor of how this differs from other sheet- or view-creation tools in the sibling list.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, so the safety profile is covered structurally. The description usefully adds behavior beyond that: unbounded 3D views render the whole model shaded at fine detail, and box values are in model millimetres. It still omits what the dry_run flag does and whether creation permanently alters the document, so it adds moderate rather than rich 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?

Three short sentences, front-loaded with the core action, then the 3D-view default, then the box unit convention. No filler and nothing repeated from the 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?

For a 12-parameter destructive creation tool with 8% schema coverage, the description is far too thin. Although an output schema exists so return values need no explanation, the absence of usage guidance, dry_run semantics, and per-parameter meaning leaves the agent under-informed for a non-idempotent, destructive operation.

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

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

Schema description coverage is only 8% across 12 parameters, so the description bears most of the burden and fails to carry it. It clarifies only box units (mm) and the 3D default rendering; level, scale, template, element_ids, detail_level, display_style, view_family_type, dry_run, name and document are never explained beyond their schema names.

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 clear verb ('Create') plus resource ('view') and enumerates the supported kinds (plan, section, 3D, drafting), which matches the 'kind' enum. However, it does not distinguish itself from view-creating siblings such as revit_duplicate_view or revit_apply_view_template, so an agent must infer which creation path to take.

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

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

There is no explicit guidance on when to use this versus alternatives like revit_duplicate_view or revit_create_schedule, and no stated prerequisites (e.g., an open document). The only conditional hint is implicit: that a 3D view with no box is unbounded. No exclusions or routing to sibling tools are provided.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, so the safety profile is known. The description adds genuinely useful behavior beyond that: units are mm, and a null wall_type silently falls back to the first basic type. However, it says nothing about the dry_run flag, which is the key safety affordance for a destructive creation 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 tight sentences, zero filler, with the core action front-loaded before the unit and default-type caveats.

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 essential geometry/units are covered. But for a destructive 7-parameter mutation tool, the undocumented dry_run flag and the multi-document selection requirement leave meaningful 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 only 14% (just the document param), so the description carries real weight and does explain start_mm/end_mm as XY in mm, height in mm, and the null wall_type fallback. It leaves dry_run's meaning and the level-matching semantics of the 'level' string unexplained, so compensation is partial.

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 ('Create a straight wall'), plus the placement constraint (on a named level) and unit conventions. It does not distinguish itself from the closest sibling, revit_walls_from_cad, which also produces walls, 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?

No guidance on when to use this over revit_walls_from_cad, revit_place_family, or batch alternatives, and no statement of prerequisites such as which document must be active. Usage is only implied by the verb.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds meaningful context beyond them: deletion cascades to Revit dependencies, the reported count includes dependents, and a >500 threshold gates execution behind a confirm_token. It stops short of stating whether the operation is undoable or what permissions it 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?

Three compact sentences, front-loaded with the core action and cascade behavior, then the dry_run and confirmation mechanics. No filler or repetition of the title.

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 correctly focuses on the destructive cascade and confirmation flow. For a destructive tool with low schema coverage it is largely complete, though element_ids semantics and undo/reversibility guidance 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 coverage is only 25% (only 'document' is described), so the description must compensate. It clarifies dry_run and confirm_token semantics well, but leaves the required element_ids undocumented (beyond an intuitive name) and adds nothing about the document 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 description gives a specific verb (delete) and resource (elements and their Revit dependencies), and signals scope by noting the count includes dependents. This clearly distinguishes it from sibling mutation tools like revit_remove_links or revit_change_type.

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 the conditional workflow: dry_run returns a count, and above 500 elements a confirm_token from a first call is required, while revit_run_actions refuses such deletions. It does not, however, say when to prefer this over alternatives such as revit_undo_last or how it relates to revit_remove_links.

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, so the lower bar applies, yet the description still adds real value: "No Undo" confirms irreversibility and the "two-step AI app token handshake" plus confirmation challenge disclose an auth/protocol requirement an agent must plan for. It stops short of saying what state is left behind or what the token challenge returns.

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 action and the irreversibility warning, with no wasted wording. The brevity is only a problem where it creates ambiguity about the deletion target, not where it pads.

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 destructive two-parameter tool the description should at minimum identify what object the `name` refers to and how the confirmation handshake is sequenced. The mismatch between "revisions" and a tool-deletion name leaves the agent unable to invoke this confidently.

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

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

Schema description coverage is 0% and the description never explains the required `name` parameter or its regex pattern, which is the primary identifier for the operation. It only gestures at `confirm_token` via "two-step token handshake," without stating the token's format, source, or that it is optional and defaults to null.

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 says it deletes "all revisions," but the tool name is revit_delete_tool and its siblings (revit_save_tool, revit_list_tools, revit_get_tool) strongly imply it removes a saved tool definition, not model revisions. An agent cannot tell which resource is actually destroyed, and the title "Delete My Tool" is tautological filler.

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

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

There is no guidance on when to choose this over the sibling revit_delete, nor any prerequisites such as required permissions or what happens if the tool is in use. The only procedural hint is the phrase "after a first confirmation challenge," which describes a step but not when the tool is appropriate.

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 safety is covered by structured data. The description earns credit beyond that by disclosing units (elevations in mm) and, importantly, that results can be partially incomplete ("skipped means incomplete; skippedCount is the total skipped"), which is real behavioral context an agent cannot get from the 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?

Two short sentences, content front-loaded, no filler. The second sentence is compressed to the point of being cryptic — "skipped" is named without saying what a skipped item is or which result section it appears in.

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 a full output schema and complete annotations, the description only needs to frame the tool, which it does by listing the data returned plus the partial-result caveat. The one gap is that the skipped/skippedCount note is under-explained relative to how much it matters for interpreting results.

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 document, process_id and timeout_seconds are already fully documented in the schema; the description adds no parameter-level meaning. It does contribute the mm unit for level elevations, but that concerns output rather than input semantics.

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

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

Opens with a specific verb ("Read") and enumerates exactly what is returned: file name, Revit version, levels with mm elevations, area schemes, worksets, view count. That is far more specific than the sibling revit_documents or revit_ui_state, though the description never names those siblings to make the distinction explicit.

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

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

The phrase "the active model's" implies the usage context (you want metadata about the currently active document), but there is no explicit when-to-use vs. revit_documents / revit_model_snapshot / revit_view_summary, and no note on what to do when multiple documents are open despite the schema having document and process_id selectors.

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 largely covered. The description does add real behavior — background documents are included, linked documents are conditionally excluded, and 'skipped'/'skippedCount' are explained — which is useful context beyond the annotations, though return shape details are already handled by the output schema.

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

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

Three short sentences, front-loaded with the primary behavior before the conditional flag and the skipped-field glossary. The skipped/skippedCount sentence borders on redundant given an output schema exists, but it is compact and non-repetitive.

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 listing tool with a full annotation set and an output schema, the description covers scope, the conditional linked-document behavior, and the meaning of skipped results — enough for an agent to call it correctly. Only explicit routing to sibling tools 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 75%, so the baseline is 3, but the description meaningfully compensates for the one undocumented parameter by explaining that linked documents appear only when include_linked is set. It does not restate the document/process_id precedence or timeout_seconds, but those are already covered in 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') with an explicit scope qualifier ('including background documents') that rules out a repo-wide listing. It does not name the sibling it differs from (e.g., revit_list_instances for processes or revit_document_info for a single doc), so differentiation is implied by scope rather than stated.

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

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

Usage context is implied rather than stated: 'one Revit process' and the include_linked sentence tell the agent how the result set changes with a flag, but there is no explicit when-to-use guidance or named alternative for listing open documents versus instances or document info. The agent must infer selection from sibling names.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=true, covering the safety profile, so the description needed to add context such as what a dependent view inherits, that duplication persists new elements to the model, or how the auto-generated name is chosen. It adds none of this, essentially restating the mode enum.

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

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

A single front-loaded sentence with no wasted words. It is efficient, though its brevity comes at the cost of the missing behavioral and parameter detail noted elsewhere.

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

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

Output schema and annotations relieve the description of return-value and safety obligations, but for a destructive 5-parameter tool it omits the name defaulting behavior, the purpose of dry_run, and what "dependent" implies for view hierarchy. An agent can invoke it, but not confidently.

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

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

Schema description coverage is only 20% (just the document param), so the description must carry the semantic load for view, mode, name and dry_run. It only hints at mode semantics via "with detailing or as a dependent view" and says nothing about name defaulting to an auto-generated value or what dry_run does for a destructive operation.

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

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

The description states a specific verb and resource ("Duplicate a view") and names the two non-default variants (with detailing, dependent), so an agent can tell it apart from revit_create_view. It does not, however, clarify how it relates to sibling view-creation tools beyond the word "duplicate".

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

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

There is no guidance on when to duplicate vs. use revit_create_view, no prerequisites (view must be active/valid, document must be open), and no mention of when to prefer a dependent view over a full duplicate. The optional variants are named but their selection criteria are not explained.

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 and non-idempotent. The description adds that a dry run rolls back all changes and that execution may commit and be polled via revit_jobs, which is real value. However, it does not say what specifically gets destroyed, what 'may commit' means operationally, or that a document must be open/active.

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?

Very short and front-loaded, with no wasted filler. But it is compressed to the point of ambiguity, using fragments like 'May commit; revit_jobs polls; retry repeats' that require the reader to guess the subject.

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

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

This is a complex, destructive, multi-operation tool with 7 parameters and nested operation schemas. The description covers only the family targeting and dry-run behavior, leaving the operation vocabulary and error/timeout behavior unexplained. An output schema exists, so return values need not be covered, but the input side remains 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 description coverage is only 14% across 7 parameters. The description only clarifies 'families' (exact names or ["*"]). The four operation types, stop_on_error, timeout_seconds, and overwrite_parameter_values receive no explanation in either schema or 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 clear verb and resource: edit an open family in place, or named project families. This distinguishes it from revit_load_family and revit_place_families by implication. The phrase 'one load cycle each' is opaque jargon that weakens otherwise solid clarity.

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?

Adds useful operating guidance: use dry_run to roll back, poll with revit_jobs, retry repeats. It does not say when to prefer this over revit_update_parameters or revit_set_parameter, so the agent gets no comparative routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: geometry units (model mm), the meaning of roomCenterMm, and that 'skipped' signals incomplete results with skippedCount as the total — non-obvious output semantics worth disclosing.

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 in the first clause, then three short clauses covering units, a named field, and skip semantics. No filler or repetition, and each clause carries information an agent would otherwise have to guess.

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 structure need not be explained, yet the description proactively clarifies two easily misread fields (roomCenterMm, skipped/skippedCount). Combined with the annotation-covered safety profile, this is nearly complete; only multi-instance/document targeting context is left entirely to the 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 description coverage is 100%, so all four parameters (document, element_id, process_id, timeout_seconds) are already documented, including process_id taking precedence over document. The description adds only the 'by Revit ID' framing and nothing about timeouts or document disambiguation, 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 ('Read') and a well-defined resource ('parameters and geometry of an element by Revit ID'), plus what is bundled in (type parameters, related warnings). It is clear what the tool returns, though it never names the sibling it contrasts with (e.g. revit_query_elements), so an agent must infer the distinction.

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

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

Usage is only implied: 'by Revit ID' hints that an ID must first come from a query tool, and the schema's element_id field names revit_query_elements/revit_view_elements as sources. There is no explicit when-to-use versus when-to-use-something-else statement, and no exclusions or prerequisites for multi-document scenarios.

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 flag the tool as destructive and non-idempotent, and the description adds the critical mechanics: transaction ownership modes, the requirement to close all scopes before returning, that transaction="none" is refused, that dry_run rolls back, that the call may commit, and that retry repeats the operation. These are exactly the behaviors an agent needs to avoid corrupting a model.

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

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

Purpose is front-loaded and nearly every clause carries load-bearing information (threading, transaction modes, confirmation, rollback, polling). The telegraphic style ('retry repeats') is terse to the point of being slightly cryptic, costing a little clarity.

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-risk arbitrary-code-execution tool with an output schema already present, the description covers threading, transaction handling, confirmation, rollback, and follow-up via revit_jobs. The main omission is how an agent obtains a confirm_token and any sandbox/namespace limits on the code, which would round out 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 17% schema description coverage, the description does the heavy lifting: it explains the transaction enum ('auto' owns, 'group' lets scripts own scopes in one Undo group, 'none' refused), the confirm_token requirement, and dry_run's rollback semantics. It leaves timeout_seconds and the 200000-char code limit unexplained, so a small gap remains.

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 action (run C# code) and two accepted code forms ('C# body or public static Script.Execute(ScriptContext ctx)'), plus the execution context ('on the Revit thread'). This is unmistakably different from the CRUD/view siblings, and it points to revit_api_lookup as the metadata source and revit_jobs for polling.

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 operating guidance: use revit_api_lookup for API metadata, choose 'auto' vs 'group' for transaction ownership, and confirm_token is required except for dry_run. It does not explicitly say when to prefer this tool over revit_run_tool/revit_run_actions, so the when-not is implied 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?

Goes well beyond the annotations by disclosing the two-step confirm_token flow for overwrites, that Model MCP shows no dialog of its own and the host app must surface the action, and that the call may commit a job that is polled via revit_jobs. That is exactly the destructive/async/auth context an agent needs before calling, and it is consistent with destructiveHint=true and idempotentHint=false.

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

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

Front-loads the core action and file types, then layers on the overwrite handshake and job semantics. The trailing telegraphic sentence 'May commit; revit_jobs polls; retry repeats' is terse to the point of ambiguity but earns its space.

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?

Return values are covered by the output schema and the destructive/async behavior is well described, but for a 12-parameter export the selection semantics are incomplete: an agent cannot tell what happens if views and sheets are all omitted, whether all_sheets or sheet_set take precedence, or what options and timeout_seconds control.

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 8% schema description coverage across 12 parameters, the description carries real weight and does explain the highest-risk ones: output_dir, dry_run, overwrite and confirm_token. However it says nothing about views, sheets, sheet_set, all_sheets, options, document or timeout_seconds, leaving most of the parameter surface undocumented 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 plus the exact output artifacts: saves PDF, DWG, IFC and schedule CSV files to a named folder on the Revit workstation. An agent knows what the tool produces. It stops short of naming the obvious siblings (revit_export_view, revit_export_nwc) that also export, so the boundary is inferred from the format list 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?

Gives concrete operating guidance: use dry_run to preview planned file names, use overwrite only with the confirm_token handshake, and poll revit_jobs because the operation may commit asynchronously. It does not say when to choose this over revit_export_view or revit_export_nwc, which is the main gap.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds genuinely new behavior: overwrite triggers a two-step confirm_token handshake, the AI app (not Model MCP) is responsible for showing the action to the user, and settings_xml values are overridden by explicit arguments. The phrase 'May commit' is cryptic about what side effects occur on the document, which keeps it 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 action is front-loaded in the first sentence and there is no filler. The telegraphic tail ('May commit; revit_jobs polls; retry repeats.') is compact but reads as shorthand that costs some clarity.

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 overwrite/permission workflow is covered. For a 24-parameter export tool with 4% schema coverage, the description leaves most export options semantically unexplained, which is a meaningful gap even though the invocation path (path, overwrite, confirm_token) is clear.

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 4%, so the description must carry the parameter burden, yet it explains only path, overwrite/confirm_token, and settings_xml precedence. The remaining ~20 exporter options (scope, coordinates, faceting_factor, divide_file_into_levels, element_ids, timeout_seconds, etc.) get no meaning beyond their bare names.

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 names a specific verb and artifact: save an NWC file to a user-named folder path on the Revit workstation, and it notes the Navisworks exporter dependency. It is clearly distinguishable from the generic revit_export and revit_export_view because the output format is stated, though it never names those siblings explicitly.

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

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

It gives a prerequisite (Navisworks exporter must be installed) and post-call guidance ('revit_jobs polls; retry repeats'), plus a hint that overwrite requires a confirm handshake. It never says when to choose this over revit_export or revit_export_view, or when dry_run should be used instead of a real export.

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 beyond the annotations meaningfully: it discloses that existing files are refused (no silent overwrite), that the active view and model stay unchanged (consistent with destructiveHint=false), that omitting output_path falls back to a temporary folder, and what skipped/skippedCount signify. That is real behavioral context not encoded in the hints. It stops short of covering failure modes or how many items can be skipped, so not 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?

Five short sentences, each carrying a distinct fact: action, output naming, overwrite policy, model side effects, skip semantics. The core action is front-loaded with no filler or hedging. The closing skipped/skippedCount line is terse to the point of being slightly cryptic, but it 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 single-view PNG export with a full output schema, the description covers what an agent needs: where the file lands, overwrite behavior, and that the model is untouched. It does not explain the return payload shape, which is acceptable since an output schema exists, but it omits error conditions beyond existing-file refusal.

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 five parameters are already documented, including output_path's temp-directory default and localPath return. The description restates the output_path fallback and clarifies that the path resolves on the AI app machine, which adds a little, but repeats rather than extends the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource: save a picture of the selected view as a PNG file. An agent can tell this is a view-to-image export, distinct from model/data tools. However, it never mentions the sibling revit_export or revit_export_nwc, so the boundary between this and other export tools is left implicit.

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

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

Usage is implied by the narrow purpose (export the currently selected view to PNG) rather than stated. There is no explicit when-to-use or when-to-prefer-another-tool guidance, and no mention of prerequisites such as the view needing to be non-template or active. An agent could infer the case but must reason about alternatives itself.

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, yet the description still adds real behavior: no save or load side effects, a 200-family wildcard cap with name sorting, and the meaning of data.skipped/skippedCount for incomplete entries. It leaves out timeout behavior and whether an active document must be open, which are worth stating for this class of 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?

Front-loaded with the core action and its no-side-effect guarantee, then mode rules, then return-shape details; almost every clause carries information. The closing pair "skipped means incomplete; skippedCount is the total skipped" is slightly repetitive but resolves a real ambiguity in the return payload.

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 five-parameter, multi-mode read tool with an output schema, the description supplies enough to call it correctly and to interpret the skip bookkeeping. The remaining gap is minor: timeout and document-targeting prerequisites are only partly covered by the schema's own parameter descriptions.

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 40%, so the description must compensate and largely does: it explains the accepted forms of `families` (exact names, ["*"], or omitted in family mode) and the semantic difference between detail="summary" and detail="full" in terms of what is returned. `timeout_seconds` remains undocumented in both schema and description.

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

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

Specific verb+resource ("Audit ... families") with an explicit scope constraint ("without saving or loading changes"), and it distinguishes its two operating modes (open family vs. named project families). It does not name or contrast with adjacent siblings such as revit_model_audit, revit_audit_report, or revit_edit_families, so an agent must infer the boundary from the words 'audit' vs 'edit'.

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 mode-selection rules: project mode requires exact names or ["*"], family mode takes none, and it explains which detail level to pick and what each returns. It stops short of stating when to choose this over other audit or parameter-check siblings, so it lacks true 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the meaningful behavioral note that no execution occurs, but leaves open what 'approved' means (approval workflow? validation state?) and what happens if the named tool is absent, which matters for an agent deciding whether to fall back to revit_list_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?

A single short sentence with no filler; the key constraint ('without execution') is placed where it will be read. It is efficient, though efficiency here partly reflects under-specification rather than tight writing.

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, and annotations cover safety. However, for a tool with a required name parameter at 0% schema coverage and four plausible siblings (list/save/run/delete tool), the description omits both the parameter's role and the routing logic, leaving real gaps.

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

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

Schema description coverage is 0% and the single parameter 'name' has only a regex pattern, no prose. The description never mentions the name argument or its format/lookup semantics, so an agent gets no help beyond guessing that it identifies the tool — the structured data does not compensate, and the description does not either.

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 'return' and object 'source and schema' point at retrieving a stored tool definition, and 'without execution' separates it from revit_run_tool. But 'approved' is undefined and the object of retrieval (a saved tool, presumably identified by name) is never stated, so the purpose is only inferable from the tool name rather than the description.

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?

'Without execution' hints that this is the inspect-instead-of-run path versus revit_run_tool, but that's the only guidance. There's no explicit when-to-use, no differentiation from revit_list_tools (which presumably enumerates tools) or revit_save_tool, and no stated precondition such as the tool needing to exist.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context by saying isolation is temporary and that an empty list restores the normal view state, but it doesn't resolve how the separate reset boolean differs from that empty-list behavior.

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

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

The description is one tight sentence with the core action and scope up front and the reset behavior appended, with no wasted words.

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

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

An output schema exists and annotations cover safety, so the bar is moderate. Still, the ambiguity between the reset parameter and the empty element_ids list leaves a calling agent without full confidence in how to restore the view.

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%, and the description explains element_ids behavior (an empty array resets) but says nothing about the reset boolean, which is undocumented in the schema and overlaps in purpose with the empty-list reset. The document parameter is described in the schema, not the description.

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

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

The description has a specific verb and resource ("Temporarily isolate element IDs in the active view") and even notes the effect of an empty list. It doesn't distinguish itself from related siblings like revit_set_view_visibility or revit_select, which also control what is visible or selected.

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?

"Temporarily isolate" plus "an empty list resets" implies when to use it, but there is no explicit contrast with revit_set_view_visibility or revit_select, and no statement about prerequisites. A reader must infer that isolation is a view-state operation that does not change the model.

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 goes well past the annotations: it discloses a 25-snapshot cap allocated 'by severity', a 210-second time budget, that failed snapshots degrade to cell notes rather than failing the run, a local/SSH transport prerequisite, and that existing output files are refused. These are exactly the operational behaviors an agent needs and none are contradicted by readOnlyHint=false / destructiveHint=false.

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

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

The critical points are front-loaded in the opening sentence, and the remaining sentences are dense with no filler. It is slightly cramped, folding return-value semantics and snapshot budgets into a single paragraph, but no sentence 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 needn't be explained, yet the description helpfully defines 'skipped' and 'skippedCount'. Limits, budget, transport, and overwrite refusal are all covered; the only real gap is the internal structure of the required issues/project objects, which is left to additionalProperties in the 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 67% and the schema already documents document, pixel_size, process_id, and output_path in detail. The description adds only that existing output files are refused (repeating the output_path schema text) and says nothing about the shape of the required issues or project nested objects. Baseline 3 applies since the schema carries most 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 artifact: 'Write a new local .xlsx issue register with element snapshots and review documents.' That is far more informative than the bare name 'Issue Register' and clearly separates it from nearby tools like revit_build_report or revit_export. It stops short of naming a sibling to disambiguate against, so 4 rather than 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?

Usage is implied through constraints ('Takes 1 to 60 issues', 'Existing output files are refused', 'Snapshots need local or SSH transport') rather than an explicit statement of when to pick this over revit_build_report or revit_model_audit. An agent can infer preconditions but gets no direct when/when-not guidance or named alternative.

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 (readOnly, idempotent, non-destructive), and the description adds real value on top: 24-hour retention on the workstation surviving server restarts, blocking wait semantics, and the meaning of skipped/skippedCount. It does not say how many 'recent jobs' are returned or how far back 'recent' reaches, which is the main remaining behavioral gap.

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

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

Two dense, front-loaded sentences with no filler; the two operating modes come first. The trailing 'skipped means incomplete; skippedCount is the total skipped' is terse to the point of being cryptic and arguably belongs to the response fields, which an output schema already documents.

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 only 5 optional params, the definition covers the essentials for the wait path but leaves the two-timer interaction unexplained and gives no sense of result volume or pagination for the listing path. Adequate but with clear gaps for a dual-mode tool.

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

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

Schema coverage is 80%, so the baseline is 3. The description only restates wait_seconds' range and default, which the schema already specifies, and never addresses the genuinely ambiguous part: how timeout_seconds (default 120) interacts with wait_seconds (max 50). That is the one clarification the description should have supplied.

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 recent jobs') plus a second blocking mode ('wait ... for the result of an action jobId'), which is clear enough to distinguish this from pure-mutation siblings. It never names the closely related siblings (revit_batch_status, revit_cancel_job, revit_run_actions), so the agent must infer the boundary itself.

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

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

Usage is implied rather than stated: mentioning 'the result of an action jobId' suggests calling after an action is submitted, and the wait mode suggests polling. There is no explicit when-to-use/when-not, and no routing to or from revit_batch_status, which likely serves a similar status-polling role.

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

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

Annotations already flag this as a non-read-only, destructive, non-idempotent operation, so the safety profile is covered. The description adds that CAD layers and extents (in mm) are returned, but says nothing about what gets modified in the model, dry_run behavior, or the timeout implication for a long-running job.

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 that lead with the action and then the return payload. Zero 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 10-parameter destructive mutation with almost no schema documentation, the description is far too thin. It does not need to restate the output schema, but the parameter behavior, prerequisites, and link/import distinction should have been covered here.

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 10% (just the 'document' param), yet the description explains none of the 10 parameters: the link-vs-import semantics of 'link', the meaning of 'auto' units, layer filtering, origin modes, or dry_run. It 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+resource (link or import a DWG) and the target context (a plan view on the Revit workstation). It is distinguishable from siblings like revit_walls_from_cad or revit_remove_links, though it never names them explicitly.

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

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

No guidance on when to link versus import, when to prefer this over revit_walls_from_cad, or what prerequisites (open document, plan view) must hold. The 'link' parameter defaults to true but the description never explains the choice.

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 safety is covered. The description adds genuinely new behavioral context beyond them: per-list truncation at 100 entries, that summary counts span all links despite truncation, and what 'skipped'/'skippedCount' mean. This is exactly the kind of non-obvious detail an agent needs to avoid misreading truncated 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?

Three short sentences, zero filler, with the core action front-loaded and the caveats (cap, skipped semantics) following in priority order. Every clause carries information.

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

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

An output schema exists, so return shape need not be described, and all three parameters are schema-documented. The description closes the main interpretive gaps (truncation, count scope, skipped fields), though it says nothing about timeouts or failure modes on a slow/large model.

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 document, process_id, timeout_seconds and their precedence are fully documented in the schema. The description adds no parameter-level meaning beyond that, making the baseline 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 ('Read') and resource ('RVT, CAD and image link status'), which is clearly distinct from siblings like revit_remove_links, revit_link_cad or revit_compare_link_datums. It does not explicitly name or contrast with those siblings, 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?

Usage is only implied by the verb 'Read' and the resource type; there is no explicit statement of when to call this versus revit_compare_link_datums or revit_model_health, and no prerequisites or exclusions. An agent can infer it is a diagnostic read, but that is left to inference.

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=true, idempotent=true, and destructive=false, so the safety profile is fully covered. The description does add genuinely useful behavior beyond that: results are bounded (default 200, max 2000), 'total' is reported before the limit, 'hasMore' signals truncation, and 'skipped'/'skippedCount' indicate the listing was incomplete. The gap is that pagination/resumption guidance is absent and the return shape is largely restated in the output schema that already exists.

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

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

The description is dense and front-loaded, leading with the operation and the valid section values before moving to filtering and result semantics. Some content is wasted repeating schema constraints ('default 200, maximum 2000'), but every remaining sentence carries information.

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

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

For a six-parameter tool with an output schema, the description covers the section domain, filtering, and truncation semantics well, so return-value explanation is not strictly needed. It is nonetheless incomplete on document/process_id targeting, which is the one non-obvious requirement when multiple Revit instances are open, and it gives no hint about which sibling listing tool to use for richer view or sheet metadata.

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?

Section is the only required parameter and lacks a schema description, so the description's enumeration of section values adds real meaning for it, and it clarifies that name_contains matching is case-insensitive. However, it repeats the limit default and maximum verbatim from the schema and says nothing about the multi-instance targeting parameters (document, process_id) or timeout_seconds, which matter for correct invocation when several Revit instances run.

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