Revit Model MCP

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 safety profile is nominally covered. The description adds the meaningful 'already open' precondition, but it never explains why an activation is flagged destructive, nor what happens if the named document cannot be found. Notably, the destructive flag is hard to reconcile with an operation described purely as bringing a document to the foreground.

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, correctly leading with the verb and resource. It is arguably too terse for a tool whose annotation profile and second parameter need explanation, but nothing is wasted.

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

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

An output schema exists, so return values need not be described. However, for a tool annotated destructive with an undocumented process_id and no failure behavior for an unopened document, the description leaves real gaps an agent would want closed before calling it.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It usefully clarifies that the required 'document' argument accepts either a title or a path reference, but the optional 'process_id' parameter is unexplained in both schema and description, leaving the agent unable to know when to supply it.

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 ('Activate') and resource ('document'), plus the identifier forms accepted ('title or path reference'). The phrase 'already open' implicitly distinguishes it from revit_open_document and revit_close_document, though neither sibling is named, 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 precondition 'already open' implies this is for switching focus among a session's open documents, but there is no explicit when-to-use statement, no guidance on erroring when the document is not open, and no named alternative such as revit_open_document for the not-yet-open case.

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=true, so the agent already knows this is a mutating, non-idempotent operation. The description adds no context on what state changes (UI focus, document activation, any prior view state lost) or why the tool is flagged destructive, which is the main 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 short, front-loaded sentences with no filler; the core action leads and the zoom options follow. It is terse to the point of underspecification, but nothing is wasted.

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

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

An output schema exists so return values need not be described, but for a 6-parameter mutating tool with near-zero schema coverage the description is far too thin: it omits four parameters, activation semantics, and the destructive behavior the annotations flag.

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

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

Schema description coverage is only 17% (only 'document' is documented), so the description must compensate. It loosely gestures at the zoom parameter ('fit', 'preserve zoom', 'frame element IDs') but leaves view_type, process_id, activate_document, and the element-ID array format entirely unexplained.

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

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

States a specific verb and resource ('Activate a non-template view') and adds a scoping qualifier that separates it from revit_activate_document and revit_list_views. It is clear what the tool does, though it does not name the sibling it is being distinguished from.

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 lists zoom modes but never says when an agent should activate a view versus opening/activating a document, nor any precondition (e.g. view must not be a template is asserted but not framed as guidance). No when-not or alternative routing 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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds genuinely new behavioral context: unit conventions (mm, m2, m3) and, importantly, result-completeness semantics — a non-empty skipped list means the result is incomplete and skippedCount counts all skipped entries. That is exactly the kind of caveat an agent needs and cannot get from annotations.

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

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

Four short sentences, all front-loaded with the core operation first, then units, then the area-scheme special case, then the completeness caveat. No filler and every sentence carries actionable content.

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

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

For a 15-parameter aggregation tool with an output schema, the description covers the operation, units, the area-totals path, and result completeness, which is the essential context. Minor gaps remain around how parameter_filters interacts with group_by and the document/process_id precedence, but these are secondary.

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 67% schema description coverage, the schema documents several params, but the description adds meaning the schema lacks: the mm/m2/m3 unit convention tied to sum_field, the rule linking area_scheme to level-based area totals, and the one-or-two-field constraint on group_by. It does not explain the timeout or document/process_id precedence relationships, so it is not exhaustive.

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 (summarize/aggregate) and resource (matching elements) plus the aggregation mechanism (one or two group-by fields with optional sum/average). It is clearly distinct from listing tools like revit_query_elements or revit_view_elements, though it never names a sibling to sharpen the contrast.

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

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

It gives one concrete conditional rule: 'For area totals, group by level and select the area scheme.' That is useful procedural guidance, but there is no explicit statement of when to prefer this tool over revit_query_elements or revit_schedule_data, and no exclusions or prerequisites.

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

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

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 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?

The annotations declare readOnlyHint=true, but the description claims side effects: 'Persist cancellation and prevent unstarted models from running' is a state-changing, queue-altering operation, not a read. This directly contradicts the readOnlyHint, and no additional behavioral context (partial cancel semantics, already-finished runs, idempotency) is offered.

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

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

A single compact sentence with the key effect front-loaded and no filler. It is appropriately sized, though it omits detail that a one-parameter mutation tool would benefit from.

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

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

An output schema exists so return values needn't be explained, but for a cancellation operation the description leaves out relevant behavior: what happens if the run already completed, whether cancellation is gradual, and what identifies the run. Combined with the annotation conflict, the definition is not complete enough.

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

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

Schema description coverage is 0% for the single required run_id, and the description never mentions it or its expected format. The parameter name is reasonably self-explanatory, but the description does nothing 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?

The description states a specific action (cancel a batch) and its consequences: 'Persist cancellation and prevent unstarted models from running.' An agent can tell this controls an in-flight batch job rather than a document. It does not, however, distinguish itself from the sibling revit_cancel_job or explicitly name the batch run it operates on.

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

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

No when-to-use guidance is given. With siblings like revit_cancel_job, revit_batch_status, revit_batch_start, and revit_batch_fetch, the description never says when this tool is the right choice versus those alternatives, nor any precondition (e.g., run must be active).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false, covering the safety profile. The description adds one genuinely useful trait — that files land in new local files "without overwriting" — but says nothing about what happens if the run is incomplete, how many files are produced, or failure behavior.

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

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

A single front-loaded sentence with no filler; the non-overwrite constraint is placed where it reads. It is efficient, though the terseness comes at the cost of the 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?

An output schema exists, so return values need not be described, but for a two-parameter tool with zero schema coverage the description omits parameter meaning, preconditions (run must be complete), and multi-file output expectations. Too thin for the complexity involved.

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 neither parameter is documented in either place. The description does not clarify what run_id identifies (a batch run id) or that output_dir is the local destination directory, leaving both required parameters semantically opaque.

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

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

The description gives a verb and resource ("Download completed snapshots"), which is more specific than the title alone, but "snapshots" is ambiguous next to siblings like revit_model_snapshot and revit_batch_status, and nothing ties it to the batch workflow implied by the name.

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

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

There is no explicit statement of when to call this versus revit_batch_status, revit_batch_cancel, or revit_model_snapshot. "Completed" weakly implies it should follow a finished batch run, but the agent must infer the workflow sequencing entirely.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds useful operational context: the run is persistent, targets local/UNC/RSN models, and open_timeout_minutes defaults to 30 (45 when upgrading in memory). It does not discuss idempotency or job lifecycle, but adds meaningful behavior 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?

Two sentences, front-loaded with the core purpose and then a parameter detail. There is no filler or repetition, and the structure is easy to parse.

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

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

For a 6-parameter batch-start tool with no required fields and no schema parameter descriptions, the description is far too sparse. It omits what is being collected, how to specify input scopes, and the meaning of most parameters, though the existence of an output schema means return values need not be explained.

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 there are 6 parameters, so the description carries the burden of explaining them. It only explains open_timeout_minutes, leaving paths, years, folder, recursive, and parameter_rules completely undocumented 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?

States a specific verb ('Start') and resource ('persistent, read-only run over local, UNC or RSN models'), making the tool's purpose clear. It does not explicitly differentiate itself from sibling tools such as revit_batch_status or revit_batch_cancel, 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?

The description gives no explicit when-to-use guidance, prerequisites, or alternatives. It only implies usage by saying it starts a batch run, leaving the agent to infer when this should be chosen over revit_process_models or the other batch lifecycle tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value by noting the status is durable and readable after the initiating client exits, but it says nothing about what the status contains, whether it is a snapshot vs. live, or why idempotentHint is false for a read.

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

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

A single front-loaded sentence with no filler; the read action is stated immediately. It is arguably too terse rather than padded, so conciseness is not the problem.

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 safety profile is in annotations. What is still missing is the relationship to the other batch tools and any hint about the run_id's origin, which matters for a polling-style status endpoint.

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 must compensate for the undocumented run_id parameter, and it does not — no format, source, or lifecycle for the id is given. The name is self-suggestive, but nothing in the definition tells the agent where run_id comes from or what happens if it is stale.

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

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

The description names a specific verb ('Read') and resource ('run and model status'), and 'durable' hints that the run survives client exit, which is meaningful for a batch tool. It does not, however, differentiate itself from close siblings such as revit_batch_fetch or revit_batch_start, so an agent must infer the division of labor.

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 supplies a timing condition — check status 'after the initiating client exits' — which implies when it is useful. But it names no alternatives (revit_batch_fetch, revit_batch_cancel) and gives no exclusion about when this is the wrong tool to call.

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, covering the safety profile. The description adds that the report is built locally from snapshots without contacting Revit, which is useful behavioral context, though it doesn't mention auth needs, rate limits, or file-overwrite behavior (the latter is 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?

Single sentence, front-loaded with the action and output type. No wasted words; appropriately sized for a simple report-building tool.

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

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

Given the output schema exists and annotations cover safety, the description provides enough context for correct invocation. It could mention optional sheets (Changes) or findings, but the schema documents those, so no critical gap remains.

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 are fully documented in the schema. The description adds no parameter-level syntax or format details beyond what the schema already provides; baseline 3 applies.

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

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

States a specific verb ('Build') and resource ('local Excel report from snapshots') and distinguishes itself from Revit-contacting siblings via 'without contacting Revit.' It doesn't name an alternative sibling explicitly, but the scope is clear enough for selection.

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 usage when offline snapshots exist and Revit contact is undesirable, but gives no explicit when-to-use, when-not-to-use, or named alternative. The condition 'without contacting Revit' provides some context but not full 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?

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 already declare the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context: the temporary view is rolled back (no persistent model change), mode/transport options, and how the skipped list/skippedCount signals an incomplete result. It stops short of 5 only because nothing is said about permissions, rate limits, or auth.

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 action and output, then constraints and side-effect notes in dense, purposeful sentences. The final sentence about the skipped list/skippedCount is slightly cramped but earns its place by explaining the incomplete-result signal.

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?

There is no output schema, so the description rightly explains key result behavior (skipped list, skippedCount, rollback). Combined with annotations covering the safety profile and schema covering most params, an agent has enough to call this correctly. It is only marginally thin on the remaining undocumented parameter (padding_mm).

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 moderate (57%). The description adds meaning the schema lacks: the 1-500 bounds on element_ids (schema sets no min/max) and the valid mode values "3d or plan" (schema has no enum, only a default). It does not cover padding_mm, and leans on the schema for document/process_id/output_path/pixel_size, but it contributes genuine value beyond the structured fields.

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 (Render) and resource (highlighted PNG marking elements) plus scope (1 to 500 elements) and intent (issue evidence). An agent immediately knows what the tool produces. It does not, however, name or contrast itself with adjacent siblings like revit_export_view or revit_show, so it stops short of full differentiation.

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

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

"for issue evidence" implies the context of use, but there is no explicit when-to-use-vs-alternative guidance and no exclusions (e.g. when to prefer revit_export_view or revit_show instead). 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?

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?

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds no behavioral context beyond 'close' – it does not say whether unsaved view state is lost, whether the active view is protected, or how the process_id/keep_active options affect the outcome.

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, which is structurally clean. But the brevity reflects under-specification rather than effective economy given the tool's three parameters and destructive nature.

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

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

An output schema exists so return values need not be explained, and annotations cover safety. Yet with three undocumented parameters, a default of keep_active=true, and no explanation of what gets closed, the description is too thin for the tool's behavior.

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

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

Schema description coverage is 0% and all three parameters (views, process_id, keep_active) are undocumented in both schema and description. The description does not explain that views accepts a list of view names, what null means, or what keep_active defaults to, 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 (close) and resource (open UI views) scoped to the active document, which is enough to separate it from revit_close_document. However, it does not clarify whether it can close all views, a subset, or only the active view, leaving the resource boundary slightly fuzzy.

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

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

There is no when-to-use guidance, no mention of alternatives such as revit_activate_view or revit_close_document, and no preconditions. The description only says what happens, not when an agent should reach for it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description still adds genuinely new behavioral context: partial results are possible, signalled by a non-empty skipped list, and skippedCount counts every skipped entry. That is real disclosure about failure/partial-completion semantics. It omits timeout behavior and matching/tolerance effects.

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 with zero filler, front-loaded with the core action followed by the mutation guarantee and the result-completeness caveat. 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 the description is not obliged to explain return values, yet it usefully clarifies skipped/skippedCount semantics. The gap is on the input side: for a comparison tool, tolerance_mm and reuse_matching materially change results and are undocumented anywhere in prose. Adequate but with clear 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 33% (document, process_id, timeout_seconds, pickup_timeout_seconds). Twelve parameters exist and the description explains none of them, including the required 'link' and behavior-shaping options like tolerance_mm, reuse_matching, prefix/suffix, kinds and name_map. With coverage this low, the description is expected to compensate and does not.

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

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

States a specific verb and resource pair: compare host grids and levels with one loaded Revit link, with a scope limit (one link). The phrase 'Changes nothing' implicitly separates it from the read/modify sibling revit_align_link_datums, but that sibling is never named, so the differentiation is inferential 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 'Changes nothing' clause implies this is the inspection-only counterpart to align_link_datums, which suggests when to use it versus the mutating alternative. However, no prerequisite (link must already be loaded) or explicit 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 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for adding context that structured fields do not: partial-result semantics via the skipped list and skippedCount, and the unit convention (elevations in mm). It still says nothing about how the document/process_id targeting behaves in multi-instance scenarios.

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 sentences with zero filler: the returned fields come first, then the partial-result caveat. Everything an agent needs at a glance is front-loaded.

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-value structure need not be described; the description instead covers the one non-obvious output trait (incompleteness signaled by the skipped list). For a zero-required-parameter read tool with full schema coverage, nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the document/process_id precedence and both timeouts. The description adds no parameter-level detail 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?

Specific verb (Read) plus an enumerated set of resources (file name, Revit version, levels in mm, area schemes, worksets, view count) scoped explicitly to the 'active model'. That scoping distinguishes it from siblings like revit_documents and revit_view_info without the agent opening any schema.

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

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

Usage is implied by 'active model' and the read-only nature, so an agent can infer this is the metadata lookup for the current document. However, it never names an alternative (e.g. revit_documents for enumerating all open documents) or states when not to use it, so no explicit routing guidance is given.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds genuine behavioral context beyond that: background documents are included, linked documents are excluded unless include_linked is set, and the skipped/skippedCount fields signal a possibly incomplete result.

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, purpose front-loaded and no filler. The final sentence about skipped/skippedCount slightly overlaps the output schema, costing a point.

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

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

With an output schema present, return values need not be described, and the tool's optional-parameter, read-only nature is well covered. The only real gap is the absence of sibling routing.

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% (baseline 3), and the description compensates for the one undocumented parameter by explaining that include_linked controls whether linked documents appear. It also frames the 'one Revit process' scoping that motivates document vs process_id selection.

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

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

Opens with a specific verb+resource ('List every open document in one Revit process') and adds scope detail ('including background documents') that separates it from single-document tools like revit_document_info. It does not explicitly name which sibling to prefer, 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?

There is no when-to-use or when-not-to-use guidance, and no alternative is named despite close siblings such as revit_document_info or revit_list_instances. The include_linked clause describes a parameter's effect, not when to choose this tool over another.

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 only flag destructive=true and idempotent=false; the description goes substantially further by disclosing that a dry run rolls back all changes, that a long action can return status=running with a jobId while possibly having already mutated the model, that revit_jobs retrieves the finished result, and that resubmission repeats the action. That partial-application warning and the non-idempotency restatement are exactly the behavioral context an agent needs before firing a destructive batch.

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 with the scope statement front-loaded and zero filler. "one load cycle each" is slightly cryptic jargon and would benefit from a word of unpacking, 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?

An output schema exists, so return values need not be explained, and the async/jobId behavior is handled well. For a tool with four distinct operation types and seven parameters, though, the description leaves the entire operation vocabulary and the remaining five flags undocumented, which is thin for this complexity.

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

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

Schema description coverage is only 14% (one of seven parameters documented), so the description carries the burden and largely fails to pick it up. It explains the families wildcard convention and dry_run's semantics, but says nothing about operations (the op discriminator and its four variants), stop_on_error, timeout_seconds, overwrite_parameter_values, or document targeting.

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 ("Edit ... families") and distinguishes the two targeting modes: the currently open family edited in place versus named project families addressed by exact name or ["*"]. It does not, however, name or differentiate itself from near siblings such as revit_family_audit, revit_load_family, or revit_place_family, so the reader 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?

Usage is implied through the dry_run clause and the running/jobId handoff, but there is no explicit statement of when to choose this tool over alternatives (e.g. revit_update_parameters, revit_load_family) or what preconditions must hold. The families wildcard syntax is the only concrete targeting guidance offered.

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 context beyond that: geometry units (model mm), the meaning of roomCenterMm, and crucially the semantics of an incomplete result ('non-empty skipped list means the result is incomplete; skippedCount counts all skipped entries'). That is real behavioral disclosure, though it omits document-vs-process targeting behavior and timeout expectations.

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

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

Four compact, front-loaded sentences with no filler; the core action leads and the result-semantics caveat follows. It is dense rather than wasteful, though the geometry/roomCenter clause could be trimmed.

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

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

With an output schema present and annotations covering the safety profile, the description need not explain return values, and it still adds units, incompleteness signaling, and room-containment semantics. Only the absence of document/process targeting guidance and any timeout expectations keeps it from being fully complete.

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

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

Schema description coverage is 100%, so all five parameters are already documented, and the description adds only the implied 'by Revit ID' mapping to element_id. Per the rubric, full schema coverage sets the baseline at 3 with no compensating detail needed.

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

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

States a specific verb and resource ('Read parameters and geometry of an element by Revit ID') plus the scope of what is returned (type parameters, related warnings, roomCenterMm). This reads clearly as a single-element detail fetch, distinguishing it from the aggregate/list siblings like revit_query_elements, revit_aggregate_elements, and revit_view_elements.

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

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

Usage is implied (fetch details for one element ID obtained elsewhere) but the description never states when to prefer this over siblings such as revit_model_snapshot, revit_view_info, or the element-listing tools, nor any prerequisites. Adequate but with a clear guidance 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 declare destructiveHint=true and idempotentHint=false, and the description materially extends that: it explains transaction ownership and the undo entry, that transaction="none" is refused by default, that a long action may return status=running with a jobId *after possibly mutating the model*, and that resubmitting repeats the action. These are exactly the side-effect, recoverability, and non-idempotency details an agent needs and cannot get from the annotations alone.

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

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

The purpose clause is front-loaded and each following clause carries distinct, non-redundant behavioral information with no filler. It is dense to the point of being a run-on of semicolon-joined fragments, which slightly hurts scannability.

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

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

For a high-risk code-execution tool with an output schema (so return values need no explanation), the description covers the full call lifecycle: code format, transaction semantics, the confirmation handshake, dry-run safety, and the async job handoff to revit_jobs. Nothing an agent needs to invoke it safely 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?

With only 17% schema description coverage across 6 params, the description carries the load and mostly delivers: it specifies the two accepted forms of `code` (method body vs. Script class with Execute(ScriptContext ctx)), the meaning of `transaction` (auto vs. none and the default refusal), when `confirm_token` is required, and that `dry_run` needs no token. It only gestures at `timeout_seconds` via 'wait budget' and relies on the schema for `document`, 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?

States a specific verb and resource ('Compile and run C# against the live Revit API') and pins down where it executes ('on the Revit thread'). The 'execute arbitrary code' framing clearly separates it from the numerous narrow siblings like revit_run_actions, revit_update_parameters, and revit_batch_start without needing to open any schema.

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

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

The description is rich on *how* to invoke (two-step confirm_token flow, dry_run needing no token, resubmission behavior) and routes results to revit_jobs, but it never states *when* to prefer this escape hatch over the many purpose-built sibling tools. It implies usage through mechanism rather than giving explicit when-to-use/when-not guidance or an alternative, so it lands at the implied-usage level.

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 destructive/non-idempotent annotations it discloses the two-phase confirm flow for overwrites, the partial-completion hazard ('may already have changed the model'), the status=running/jobId return shape, and that resubmitting repeats the action. That is exactly the behavioral detail an agent needs before invoking a destructive export.

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, front-loaded with the core capability before the confirmation and async caveats. Each sentence carries distinct information, though the run-on delivery of the job-status clause is slightly compressed.

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

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

For a destructive, 12-parameter export tool the description covers the risky paths (overwrite confirmation, async job handoff, partial mutation). An output schema exists so return values need not be restated, yet the unaddressed selection parameters remain a gap in an otherwise complete picture.

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 schema coverage at 8%, the description carries most of the burden, and it does explain dry_run, overwrite, and confirm_token meaningfully. However, views, sheets, sheet_set, all_sheets, options, output_dir, document, and timeout_seconds are left entirely undocumented, so nearly two thirds of the parameters gain no meaning from either source.

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

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

The description names a specific verb and resource and enumerates the four export formats (PDF, DWG, IFC, schedule CSV), which pins down scope well. It stops short of distinguishing itself from close siblings like revit_export_view or revit_export_nwc, so an agent must infer the boundary.

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

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

It gives concrete conditional guidance: use dry_run to preview planned file names, and supply a confirm_token from a first call when overwrite=true. It also routes the agent to revit_jobs when a run outlives the wait budget. No explicit when-not or sibling-alternative guidance is offered.

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 (destructiveHint, idempotentHint=false): it discloses the exporter dependency, the two-step confirm_token flow for overwriting files, the async job pattern (status=running + jobId, result retrievable via revit_jobs), the fact the model may already have been modified, and that resubmission repeats the action. That last point is consistent with idempotentHint=false, not contradictory.

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

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

Five dense sentences, each front-loaded and carrying distinct information (dependency, precedence, confirm flow, async behavior, resubmission risk) with no filler. Slightly packed, 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?

Covers the operational mechanics well, and the output schema means return values need no explanation. But for a 24-parameter export tool, the bulk of the configuration surface is unexplained in both description and schema, leaving an agent guessing how to drive view/scope/element_ids/export flags.

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% (just `document`), so the description must carry the load. It explains settings_xml precedence and the overwrite/confirm_token pairing, but leaves ~20 parameters (view, scope, dry_run, element_ids, parameters, coordinates, all the export_*/convert_* flags, faceting_factor, timeout_seconds) wholly undocumented.

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

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

States a specific verb+resource (export NWC) and adds the key precondition (requires the Navisworks exporter), which helps distinguish it from sibling revit_export and revit_export_view. It never names those siblings explicitly, so differentiation is present but not airtight.

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 operational conditions: overwrite=true requires a confirm_token from a first call, settings_xml is overridden by explicit arguments, and long runs may return status=running. However it never says when to choose this over revit_export / revit_export_view, so the when-to-use guidance 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?

With readOnlyHint and idempotentHint already declared, the bar is lower, and the description still adds real context: it confirms the active view and model are untouched, and it explains partial-success semantics (a non-empty skipped list means the result is incomplete; skippedCount counts all skipped entries). That partial-result disclosure is the kind of behavior annotations cannot express.

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

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

Three short sentences with no repetition or filler; the core action and its non-mutating nature come first, followed by the failure-mode caveat. Every 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?

An output schema exists, so return values need not be re-explained, and annotations cover the safety profile; the description covers scope, non-mutation, and partial results. The remaining gap is the absence of routing guidance among the export siblings (revit_export, revit_export_nwc), which would help an agent pick correctly.

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

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

Schema description coverage is 100%, including the view name format, document vs process_id precedence, pixel_size range, and the output_path/existing-file rule, so the schema does the heavy lifting. The description adds no parameter-level detail 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 and resource ('Export a selected view to a PNG file') and locates the output ('on the MCP client'), which distinguishes it from file-format siblings like revit_export and revit_export_nwc. It does not, however, name any sibling explicitly, so the differentiation is inferential rather than stated.

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

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

Usage is implied by the purpose (use this when you want a raster image of a view), and the schema's 'view' parameter points to revit_list_views as the source of valid names. There is no explicit when-to-use versus revit_export / revit_export_nwc guidance and no stated prerequisites, so an agent must infer 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?

Beyond the readOnly/idempotent annotations, it discloses that the audit neither saves nor loads changes (a meaningful constraint for a family operation) and explains the incompleteness signal: a non-empty skipped list means the result is incomplete, with skippedCount tallying all skipped entries. This adds real behavioral context the annotations do not carry.

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, with the read-only scoping constraint and mode semantics front-loaded and no filler. Dense but each clause carries information; readable and efficiently sized for a 4-parameter tool.

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

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

With an output schema present, return-value detail is unnecessary, and the description covers the operational modes, the no-save/no-load guarantee, and the skipped/skippedCount incompleteness semantics. Only the timeout and process_id/document precedence are left undocumented in prose, a minor gap.

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

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

Schema coverage is only 50%, so the description must compensate, and it does for the key `families` parameter: exact names or the ["*"] wildcard in project mode, none in family mode (implying it is optional). The document/process_id precedence and timeout parameter are left to the schema, which documents the former but not timeout_seconds.

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+resource ('audit ... families') and disambiguates the two operating modes (open family vs named project families). It also implicitly separates itself from mutating siblings like revit_edit_families and revit_load_family via 'without saving or loading changes', though it never names an alternative tool 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 states the two usage modes and what each expects: 'Project mode takes exact family names or ["*"]; family mode takes none.' That is clear contextual guidance on when each mode applies, but there is no explicit when-not or named alternative among the many sibling tools.

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

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

Annotations already establish the profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description usefully adds that the effect is temporary/view-scoped and that it can be cleared, which the annotations do not convey. It stops short of saying whether the isolation persists in the saved file or affects other users' views.

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

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

A single front-loaded sentence that states scope first and the reset caveat second, with no filler. Nothing could be removed without losing information.

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

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

An output schema exists, so return values need no explanation, and the operation is conceptually simple. However, with an undocumented 'reset' parameter and no differentiation from the visibility-setting sibling, the definition leaves gaps an agent must guess through.

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

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

Schema description coverage is only 33%, so the description carries more burden than usual. It does explain element_ids and its empty-list reset behavior, but it never mentions the separate 'reset' boolean parameter, leaving an agent to wonder whether reset=true or an empty list is the intended way to clear isolation.

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 (isolate) and resource (element IDs) scoped to the active view, plus a reset behavior. It is clear on its own, but it never distinguishes itself from the closely related sibling revit_set_view_visibility, which an agent could easily confuse it with.

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

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

There is no explicit when-to-use guidance, no preconditions (e.g. an active document/view must exist), and no named alternative. The word 'Temporarily' is the only signal that this is a transient visual state rather than a persistent change, leaving selection of this tool vs. set_view_visibility 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?

The description says the tool writes a new .xlsx file and refuses existing output files, but the annotations declare readOnlyHint=true and idempotentHint=true. Writing a new file modifies the environment and a second run would fail rather than repeat idempotently, directly contradicting 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 dense and front-loaded, packing operational limits and edge cases into about five sentences. It is efficient, though the run-on structure could be organized more scannably.

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

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

For a complex write tool with nested parameters and an output schema, the description covers important operational limits and failure behavior. However, it omits parameter details for half the schema and its contradiction with the read-only annotation leaves a critical gap in an agent's understanding.

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 50%, so the description must compensate. It adds the 1–60 issue limit and output-file refusal, which relate to issues and output_path, but it does not explain the project, document, process_id, or pixel_size parameters beyond what the schema already provides.

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

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

The description states a specific verb and resource: write a local .xlsx issue register with element snapshots and review documents. It is clear what the tool produces, but it does not differentiate itself from sibling reporting tools such as revit_build_report.

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 through constraints (1–60 issues, 25 snapshots, local/SSH transport, existing output refused), but it never explicitly says when to choose this tool over alternatives. No when-not guidance or sibling routing is provided.

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

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

Annotations cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description is free to add the behavioral details that matter: the 24-hour result retention 'across server restarts' and the skipped-list/skippedCount semantics for incomplete results. This is substantial, non-obvious context beyond what annotations provide.

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

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

Three front-loaded sentences cover the primary purpose, the key parameter, and result interpretation semantics. Every sentence carries information, though the result-retention and skipped-list details could be more tightly integrated.

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

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

Given an output schema exists, the description needn't explain return values, and it correctly focuses on behavioral traits (retention, incomplete results). It is nearly complete for a listing/polling tool, though it lacks explicit routing guidance to the batch siblings, which are the most likely alternatives.

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

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

Schema description coverage is 83%, so most parameters are already documented in the schema. The description nonetheless adds value by restating the wait_seconds range and default, and by explaining the semantic meaning of a non-empty skipped list and skippedCount for interpreting results. It does not, however, explain the distinction between wait_seconds, timeout_seconds, and pickup_timeout_seconds.

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

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

The description opens with a specific verb and resource ('List recent jobs'), immediately distinguishing it from the many mutation/view tools in the sibling set. It also maps to its true function of polling for a jobId's result, which no other sibling (aside from revit_batch_status/fetch) does.

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 ('wait up to wait_seconds for the result of an action jobId'), which gives some context about when to call it. However, it never explicitly names alternatives like revit_batch_status or revit_batch_fetch, nor does it clarify when to poll vs. list, or when not to call it.

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

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

Annotations already 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 readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavioral context the annotations cannot: per-list cap of 100 entries, summary counts spanning all links, and that a non-empty skipped list signals an incomplete result with skippedCount totalling all skipped entries.

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

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

Three short sentences with zero filler, front-loading the core action before the truncation semantics. 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?

With an output schema present and annotations covering the safety profile, the description only needs to add the truncation/incompleteness semantics, which it does. It is close to complete, though it could note the targeting requirement when multiple Revit instances run.

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 both timeout parameters are fully documented in the schema. The description adds no parameter-level meaning, 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 and resource ('Read RVT, CAD and image link status'), which clearly separates it from write-oriented siblings such as revit_remove_links, revit_link_cad, and revit_compare_link_datums. It is precise but does not explicitly name or contrast any sibling.

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 (e.g., revit_compare_link_datums or revit_document_info), nor any prerequisites or exclusions. Usage must be inferred entirely from the purpose sentence.

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 genuinely non-obvious behavioral context: results may be incomplete, signalled by a non-empty skipped list, and skippedCount tallies skipped entries. That is useful disclosure beyond the structured fields, though nothing is said about pagination or truncation limits.

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 packed sentences with no filler; the enumeration and the skipped-result caveat are both front-loaded and each 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?

An output schema exists, so return shape need not be restated, and the description covers section scope plus the skipped/skippedCount interpretation. For a five-parameter read-only listing tool with strong annotations this is close to complete, though it could say a word about how the document/process_id targeting interacts with the listing.

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

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

Schema coverage is 80% and the document/process_id/timeout parameters are already documented in the schema. The description's contribution is enumerating the legal 'section' values, which the schema leaves as a bare string with no enum - that is meaningful added semantics for the one required 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?

States a specific verb (list) and resource (catalog names) and enumerates the eight valid sections, which scopes the tool precisely enough to separate it from revit_list_views, revit_list_instances, and revit_list_relations. It does not, however, explicitly name any sibling or contrast itself with them.

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

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

Usage is implied by the section enumeration (you call it when you need to know what categories, levels, worksets, etc. exist), but there is no statement of when to prefer this over revit_document_info, revit_list_views, or revit_query_elements, and 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 already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine non-obvious behavior: busy or unresponsive processes remain listed with pluginResponding=false, and HTTP mode returns only the connected process — real edge-case context beyond the structured fields.

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

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

Three short sentences, front-loaded with what is listed, then the edge-case behavior. Little waste; the field enumeration is slightly redundant with the output schema but still readable and helpful.

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

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

Output schema exists so return values need no explanation, and annotations cover safety. The description complements these with edge-case and mode-specific behavior, leaving only usage routing unaddressed for a simple read-only list tool.

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

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

Schema description coverage is 100%, so the sole optional 'document' parameter is fully documented in the schema itself. The description enumerates output fields (documentName, processId, etc.) rather than adding meaning to the input parameter, 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 ('List') and resource ('Revit processes'), plus the exact fields returned (documentName, documentPath, revitVersion, processId, pluginResponding). This distinguishes it from document-oriented siblings like revit_documents, but it never explicitly names an alternative, so sibling differentiation is implied 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?

There is no explicit when-to-use or when-not-to-use guidance, nor any named alternative such as revit_documents or revit_jobs. The only hint at context is the schema note about 'needed when several Revit instances run', which lives in the parameter, not the description.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes further by disclosing incompleteness semantics ('a non-empty skipped list means the result is incomplete; skippedCount counts all skipped entries'), which is exactly the kind of partial-result behavior an agent cannot infer from annotations.

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

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

Three dense sentences with no filler; the core purpose comes first and the operational caveat last. The enumeration is telegraphic rather than prose, which is efficient here but slightly terse for a seven-parameter tool.

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

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

An output schema exists, so return values need not be spelled out, yet the description still explains the skipped/skippedCount fields that signal partial results. Relation values and their source parameter pairings are covered; only cross-tool routing guidance is absent.

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

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

Schema coverage is 86%, so the baseline is 3. The description earns above baseline by supplying the valid values for the otherwise undocumented, enum-less 'relation' parameter and by mapping each value to its required companion parameter (source_name vs source_id).

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 concrete read verb and resource ('Read model object membership or dependencies') and enumerates the five supported relation types, so an agent knows exactly what retrieves. It stops short of naming which sibling tools it supersedes or complements (e.g. revit_query_elements, revit_list_views), so sibling differentiation relies on 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 parenthetical pairings ('with source_name', 'with source_id') give conditional guidance on which companion parameter each relation value requires, which is genuinely useful. However, there is no statement of when to prefer this tool over alternatives like revit_query_elements or revit_view_elements, and no exclusions.

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

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

Annotations already declare the safe read-only/idempotent profile, so the safety burden is off the description. It does add one genuinely useful behavioral caveat: a non-empty skipped list signals an incomplete result, and skippedCount counts skipped entries. That is beyond structured data, but it is a single trait and leaves auth, rate limits, and failure modes unaddressed.

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

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

Two tight sentences with the field list front-loaded and the incompleteness caveat second. Minor oddity: 'template' is listed as a returned field even though the tool only returns non-template views.

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 skipped-list note covers partial results. However, with 47 siblings and 6 optional parameters, the definition gives no selection context, which is the main remaining gap.

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

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

Schema description coverage is 100%, so all six filter/timeout parameters are already documented in the schema. The description adds no syntax, format, or interaction details (e.g., precedence between document and process_id) beyond what the schema states, so the baseline of 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 (list views) and enumerates returned fields (id, name, type, level, scale, template) while scoping to non-template views. It is clear on its own, but never distinguishes itself from close siblings like revit_view_info, revit_view_summary, or revit_close_views.

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

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

No when-to-use guidance is offered, and no alternatives are named. With siblings such as revit_view_info and revit_view_summary present, the agent must infer which view-listing tool to pick, and nothing in the text helps.

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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context beyond them: a non-empty skipped list signals an incomplete result and skippedCount totals the skipped entries. This is useful failure-mode disclosure, though it doesn't mention permissions, rate limits, or pagination.

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 with the core purpose front-loaded and no filler. It is efficient, though the second and third sentences pack two distinct topics (drill-down and partial results) into a compact block that could be marginally clearer.

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