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

Annotations already establish this as a safe read (readOnlyHint=true, openWorldHint=false). The description adds real value by enumerating the returned payload, which matters because no output schema exists — the agent learns it gets path, units, active layer/class, counts and selection size. It stops short of clarifying what 'counts' actually counts.

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

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

One front-loaded sentence with no filler — the resource leads and the reported fields follow as a compact list. Every element earns its place.

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

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

For a parameterless read-only tool with no output schema, the field enumeration covers most of what an agent needs to decide whether to call it. The one soft spot is the vague 'counts' entry, which leaves the return payload partially underspecified.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. Schema coverage is also 100%.

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 resource (the active document) and enumerates what it reports — name, path, units, active layer/class, counts, selection size. That distinguishes it from siblings like vw_list_layers or vw_get_selection, which drill into single categories, though it never explicitly contrasts 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?

There is no when-to-use guidance, no statement of prerequisites or alternatives, and no indication of when a sibling such as vw_get_selection or vw_list_layers would be the better call. The agent must infer usage entirely from the field 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?

Adds substantial behavior beyond annotations: return contents (stdout, last expression or `result`, traceback), embedded Python version 3.9, the handle-lifetime constraint with the vs.GetObjectUuid workaround, and the non-obvious failure mode of a modal 'Script Errors' dialog rather than an exception. Nothing in the structured fields conveys any of this.

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 essential purpose in the first clause, then each subsequent sentence delivers a distinct operational fact (returns, runtime version, handle lifetime, dialog gotcha, flag semantics). No filler.

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

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

With no output schema present, the description explicitly documents what is returned, and it covers the environment, safety knob, and failure modes an agent needs to invoke this high-variance tool correctly.

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

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

Schema coverage is 0%, so the description must carry the load. It defines the execution context for `code` (`vs` in scope, returns last expression or `result`) and fully explains the operational meaning of `modifies_document` including its effect on vw_revert_last. Minor gaps: no mention of code size/time limits or argument passing, but the critical semantics are 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 and resource ('Run arbitrary Python inside Vectorworks') plus the execution environment ('with `vs` in scope'). It is immediately distinguishable from siblings like vw_vs_lookup (signature checking) and the read-only list/get tools.

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

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

Explicitly routes to vw_vs_lookup before calling ('A wrong vs.* signature can pop a modal... check with vw_vs_lookup first'), and tells the agent when to set modifies_document=False versus when not to, citing the vw_revert_last interaction as the consequence.

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 openWorldHint=false, so the safety profile is covered. The description adds nothing behavioral beyond that: it doesn't disclose the default 500 limit, truncation/pagination behavior, ordering, or what happens on a no-match query. With annotations carrying the load, a 3 is appropriate.

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 opens with the verb and then lists the filter dimensions. No filler, and the parenthetical examples earn their space by disambiguating type and record values. Dense but not bloated.

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

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

An output schema exists, so return-value explanation is not required. However, for a 9-parameter query tool with 0% schema description coverage, the description omits the limit/pagination default and gives no syntax detail for the "field == value" coupling. Adequate but with a clear hole around result-size control.

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

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

Schema coverage is 0%, so the description must compensate, and it does for most fields: class_name, layer, object_type (with example values), plugin ("Lighting Device"), record, name, and the coupled field/value pair ("field == value"). That is strong coverage of 8 of 9 parameters. It leaves the limit parameter unmentioned, which is the main 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 verb+resource ("Find objects") is specific and immediately clarifies that this is a filtered query tool. The enumeration of accepted dimensions (class, layer, type, plug-in name, record, name) makes the scope concrete. It doesn't name any sibling to distinguish itself from, but the purpose itself 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?

"Any combination" implies the filters are composable, which is mild usage context, but there is no explicit when-to-use statement, no exclusions, and no routing to alternatives such as vw_get_selection or vw_get_record. The agent must infer the use case 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 openWorldHint=false, covering the safety profile. The description adds genuine behavioral context by disclosing that a plug-in object's parameters can be retrieved by passing the plug-in name as the record, which the annotations do not convey. It says nothing about missing-record behavior or error handling.

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

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

A single efficient sentence with no filler. The plug-in clarification is somewhat parenthetically buried rather than front-loaded, 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, and annotations cover the read-only safety profile. For a simple two-parameter getter, the description plus structured fields are sufficient, with only minor gaps around parameter formatting and failure modes.

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 explains the 'record' argument can be either a record name or a plug-in name, which is valuable, but leaves 'uuid' undefined beyond the obvious and gives no format expectations.

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 resource (all field values of a record) and scopes it to an object UUID, distinguishing it from the sibling vw_set_record by implication of retrieval. It is phrased as a noun clause rather than a verb, but the intent is unambiguous.

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

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

There is no explicit when-to-use guidance, no mention of the complementary vw_set_record, and no statement of prerequisites. The only actionable hint is that a plug-in name may be passed as the record argument, which is inferable but not framed as 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description usefully adds the scoping constraint that only the active layer is scanned, but it omits any mention of the default limit of 500, meaning a large selection could be silently truncated with no warning.

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 dense sentence with the resource and field list front-loaded and no filler. It is a fragment rather than a sentence, but every clause 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 the return structure need not be re-explained. However, with an undocumented limit parameter and no routing guidance against 16 siblings, the definition leaves real gaps for an agent deciding whether and how to call 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?

There is one parameter (limit) with 0% schema description coverage, and the description never mentions it at all. The agent gets no indication that results are capped or how to raise the cap, so the description fails to compensate for the schema gap.

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

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

The description names the specific resource ('selected objects on the active layer') and enumerates the fields returned, so an agent knows exactly what this tool surfaces. It lacks an explicit verb and does not distinguish itself from sibling query tools like vw_find_objects, which is the only thing keeping it from 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 guidance on when to call this versus vw_find_objects, vw_get_record, or vw_list_layers. The agent must infer that this reads the current selection while find_objects queries by criteria. No prerequisites or exclusions are stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the mutation/non-destructive profile is partly covered. The description adds genuine value with 'One undo step', telling the agent the operation is reversible, but omits what null layer/class defaults resolve to and how it interacts with the current selection.

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, placement details front-loaded, and the undo behavior given as a compact trailing clause. No filler, though 'from the document's resources' is the only hint at prerequisite validity.

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

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

For a 7-parameter mutation tool with no output schema and non-destructive annotations, the description covers the core placement contract and reversibility but leaves the rotation parameter and the null-default behavior of layer/class unexplained.

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

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

Schema description coverage is 0%, so the description must carry the burden. It does explain x, y, z (document units, optional height), layer and class for five of seven parameters, but says nothing about the semantics of 'name' (must it exist in document resources?) or 'rotation', nor what null layer/class means.

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 (place/insert) and resource (symbol from the document's resources) with the placement coordinates, which is clear and distinct from readers like vw_list_symbols or vw_find_objects. It does not explicitly differentiate itself by name from those siblings, 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives (e.g., vw_list_symbols to discover valid names). The agent is left to infer that this is the write counterpart to the symbol-listing 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 cover readOnly, but the description adds real value beyond them: it names the default column set, the sort behavior including blank-values-last, the return type, and the side effect of writing to output_path. That side effect is the key thing an agent needs. Only missing piece is any error/permission behavior when output_path is unwritable.

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?

Compact and front-loaded: purpose first, then defaults, sort, return, side effect. No filler sentences, though the fields/position omission slightly hurts density of useful info.

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

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

The tool has an output schema, so return format needn't be over-explained, but two of five parameters (fields, position) are undocumented and the tool-vs-sibling choice isn't covered. Adequate for a read-only exporter, but not complete.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it partially does: it documents sort_by (with blank-last semantics), format (CSV/JSON text returned), and output_path (writes file). But fields and position are never explained, leaving two parameters undocumented anywhere.

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

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

States a specific deliverable: a paperwork export of Lighting Devices with named contents (channel hookup, instrument schedule). Clearly distinct from vw_list_lighting_devices and vw_set_lighting_device_fields.

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 (you want a report/hookup export), but it never explicitly contrasts with vw_list_lighting_devices or says when to choose the list tool instead. No exclusions or prerequisites stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that matching is case-insensitive, but says nothing about ordering, result size, or empty-result 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 short sentence with the resource and filter behavior front-loaded and no filler. It errs slightly on the terse side for a tool with a nullable parameter, but nothing is wasted.

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

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

For a simple read-only listing tool with an output schema (so return values need no explanation) and one optional parameter, the description covers the essential behavior. Only the parameter's name/default mapping and any result ordering are unaddressed.

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

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

Schema description coverage is 0%, so the description carries the burden for the single parameter, and it does add real meaning: matching is a case-insensitive substring rather than an exact or prefixed match. However it never names or maps the parameter or states the default (null = no filter), leaving a 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 'list' and the resource 'class names' with the optional filter behavior, so an agent can distinguish it from siblings like vw_list_layers or vw_list_symbols by resource alone. It stops short of explicitly differentiating itself from those siblings, but the resource is clear.

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

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

The description gives no when-to-use guidance, no prerequisites, and never names an alternative such as a search or find tool. 'Optionally filtered' describes the parameter, not the context in which the tool should be selected.

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 openWorldHint=false, so the safety profile is covered. The description contributes the useful fact that both design and sheet layers are included and that visibility plus the active layer are reported, which is real value beyond the annotations, though nothing about ordering or completeness is stated.

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 fragment with no wasted words. It is under-specified rather than verbose, but it is front-loaded and easy to scan.

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

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

An output schema exists, so return structure need not be explained, and a zero-param read tool has few moving parts. Still, the description is a noun phrase rather than a statement of behavior, leaving the agent to guess whether this is a full enumeration or a filtered subset.

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

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

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate beyond confirming the tool takes no input.

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 fragment conveys the resource (layers, both design and sheet) and the attributes returned (visibility, active one), so an agent knows roughly what it gets. But there is no verb and no explicit differentiation from siblings like vw_list_classes or vw_get_selection beyond the noun itself.

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

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

No when-to-use context, no prerequisites, and no mention of alternatives among the many list_* siblings. The agent must infer that this is the read-only enumeration counterpart to any layer-setting tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is established. The description still adds real behavioral context beyond that: rows are sorted by position then unit number, each row carries a uuid, and `fields` accepts any Lighting Device parameter name. It omits any note on the 5000 default limit or truncation behavior.

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

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

The core statement is front-loaded and efficient. The long default-fields enumeration is verbose but defensible because it tells the agent which columns exist without a schema lookup; it is the only part that strains 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?

With an output schema present, return values need not be documented, and the description already hints at the uuid key. Read-only safety is covered by annotations, filtering and field selection are covered. The one real gap is the meaning/effect of the limit parameter.

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, and it largely does: `fields` is explained as an override with the allowed value space, `position` as an exact name match, and `layer` as a filter. Only `limit` (default 5000) is left unexplained by either the description or the schema.

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

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

The description gives a specific verb+resource (list all Spotlight Lighting Devices) plus scope and sort order, so the agent knows exactly what comes back. It does not, however, distinguish itself from close siblings like vw_lighting_device_report or vw_find_objects, leaving the agent to infer which listing/query tool to pick.

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

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

It states the two filterable dimensions (exact position name or layer) and how to override the returned fields, which implies the usage context. But there is no explicit when-to-use or when-not-to-use versus vw_lighting_device_report, vw_get_selection, or vw_find_objects, so routing remains implicit.

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=true and openWorldHint=false, so safety is covered. The description adds valuable non-obvious behavior: it aggregates devices by position, reports a count of devices with no position, and flags device position names that have no matching position object — that last bit is a data-quality disclosure an agent couldn't guess 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 compact clauses, each carrying distinct information: what counts as a position, device association, and the two diagnostic reports. Slightly dense parenthetical enumeration but no wasted text.

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

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

For a read-only listing tool with annotations and one param, the description covers outputs conceptually but not the include_devices toggle, and with no output schema the agent has only prose to infer the return shape. Adequate but with clear gaps given output schema 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 0% and there is one boolean parameter, include_devices, defaulting true. The description never explains what setting it false does (presumably skips the device lists and returns just positions), which is the one parameter-level nuance an agent would need. Baseline 3 applies for a single param, but the gap is real.

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 (lighting positions), and enumerates exactly what object types count as positions (Light Position Obj, Lighting Pipe, Ladder, Truss, Hanging Position). This distinguishes it clearly from the device-oriented siblings like vw_list_lighting_devices and vw_lighting_device_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 its content (you get positions plus the devices naming them), but never says when to prefer this over vw_list_lighting_devices or vw_lighting_device_report. The relationship to those siblings is inferable but not explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully adds that folder paths accompany results and that filters are substring matches, but it says nothing about the 1000-item limit default, truncation behavior, or case sensitivity of the substring match.

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

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

One front-loaded sentence that names the resource first and the filtering behavior second, with no filler. The phrasing 'Symbol definitions in the document's resource list' is slightly noun-heavy but still 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?

For a read-only list tool with an output schema (so return shape needs no explanation), the description covers what is listed and how to filter. It is nonetheless incomplete on the limit/pagination behavior and on how 'folder' matching interacts with 'name_contains' when both are supplied.

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

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

Schema coverage is 0%, so the description must carry the load. It clarifies the matching semantics for two of three parameters ('name and/or folder substring'), but the 'limit' parameter is entirely unmentioned, leaving the caller with no idea that results can be capped at 1000.

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 ('Symbol definitions in the document's resource list') and adds what is returned ('with their folder path'), which distinguishes it from sibling listers like vw_list_layers and vw_list_classes. It never names an alternative tool, 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 parenthetical '(e.g. fixture lookup)' hints at a use case, and the filter clause implies when the tool is useful. However, there is no guidance on when to prefer this over vw_find_objects or vw_vs_lookup, and no statement of prerequisites (e.g. an open document).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavior beyond that: it lists the three returned values and discloses a warning-on-mismatch condition, which is non-obvious diagnostic behavior. It does not cover failure modes (e.g. what happens when the bridge is unreachable), keeping it out of the top band.

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; the purpose and return payload are front-loaded before the warning behavior. 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?

For a zero-argument diagnostic with no output schema, the description sufficiently explains what comes back and the key behavioral signal (version-mismatch warning). An agent has enough to call it correctly, though it doesn't say what output looks like on connection failure.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify beyond confirming it is argument-free.

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 ('Check the Vectorworks bridge') and enumerates what it returns (Vectorworks version, active document, bridge version), which distinguishes it from data-retrieval siblings like vw_document_info. It stops short of explicitly naming the sibling it replaces, so it lands just under the top band.

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

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

Usage is implied rather than stated: the mention of warning on a version mismatch suggests this is a connectivity/health check run before other operations, but there is no explicit 'use this when...' or 'do not use this for...' guidance. No alternatives are named.

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

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

Annotations confirm a mutating but non-read-only-safe operation (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds real context beyond them: what state is restored, that the effect is scoped to MCP-originated writes only, and that repeated calls step back further. It does not say what happens when there is nothing to revert (error vs no-op), and 'deletes the symbol' sits in mild tension with destructiveHint=false, though the undo framing makes it a restore rather than a destruction.

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

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

Three tight sentences, front-loaded with the core action, then the scope of what gets restored, then the repetition and limitation notes. No filler; every clause carries 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?

For a zero-parameter, no-output-schema undo operation, the description covers scope, repeatability, and the one major limitation (vw_exec_python edits). Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes no parameters, so 4 is the baseline. The description correctly implies no arguments are needed and adds no misleading parameter talk.

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 precise verb+resource ('undo exactly the last MCP write in the active document') and immediately scopes it by naming the sibling tools whose effects it reverses (vw_set_record, vw_set_lighting_device_fields, vw_insert_symbol). An agent can distinguish it from vw_exec_python and the setters without opening any schema.

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

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

Gives explicit invocation guidance ('Call repeatedly to step further back') and explicit exclusions: raw vw_exec_python edits can't be reverted this way, and Cmd-Z merges consecutive MCP edits so this tool is the fine-grained alternative. This is exactly when-to-use plus when-not-to-use.

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 write/non-destructive profile, and the description adds substantial behavior beyond that: validation-first all-or-nothing semantics ('if any fail, nothing changes'), single-step undoability, the UniverseAddress source-of-truth caveat, and the return shape including a not_applied list for overridden values. This is rich context that structured fields 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?

Front-loads the core action in the first sentence, then progressively details selectors, validation, revert, and return behavior. Every sentence earns its place with no filler.

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

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

Despite a 1-param tool with 0% schema coverage, the description supplies selector syntax, validation semantics, revert path, and return format. Even with an output schema present, it adds enough that an agent could invoke it correctly on the first try.

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

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

Schema coverage is 0%, so the description must carry the full burden, and it does: it defines the shape of `updates` as {selector, fields}, enumerates every selector variant (uuid, position+unit_number, unique unit_number, unique channel), and gives a concrete example. This fully compensates for the empty schema.

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

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

States a specific verb (bulk-edit), resource (Lighting Device fields), and a distinguishing scope constraint (one undo step). An agent can immediately tell this apart from vw_set_record or vw_list_lighting_devices without opening a schema.

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

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

Gives clear context: it routes the agent to vw_revert_last for undoing and notes Universe/DMX edits go via UniverseAddress. However, it never explicitly states when to prefer this over sibling setters like vw_set_record, so it stops short of full when/when-not 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 the mutation profile (readOnlyHint=false, destructiveHint=false), so the bar is lower, yet the description adds real value: validation happens before any change (atomicity), the operation is a single undo step, and it returns the record. It is consistent with destructiveHint=false rather than contradicting it.

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 clauses, front-loaded with the action and scope, followed by the two behavioral guarantees an agent cares about. No sentence is wasted and nothing is buried.

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

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

An output schema exists, so return values need not be described, and annotations cover safety. The remaining gap is the undocumented uuid/values parameters, but overall the definition gives an agent enough to invoke the tool correctly.

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

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

Schema description coverage is 0% for three required parameters, so the description must compensate. It clarifies that 'record' names the record/plug-in and 'values' holds field names (unknown ones rejected), but leaves 'uuid' and the shape of the nested values object 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 ('Set record fields (or plug-in parameters) on one object'), which clearly separates it from the read-path sibling vw_get_record. It does not, however, name any alternative such as vw_set_lighting_device_fields, so sibling differentiation is only implicit.

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

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

The description explains what happens during the call but never states when to choose this tool over vw_get_record, vw_set_lighting_device_fields, or vw_revert_last. Usage is only inferable from the verb, with 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine context beyond that by emphasizing 'live' and 'of the running Vectorworks', telling the agent it queries dynamic in-process state and requires an active instance. It does not mention indexing/refresh behavior, result volume, or what happens for a query with no matches.

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 the action and scope front-loaded and examples used efficiently as illustration. Slightly more compactness is possible (the parenthetical and example list could be tightened), 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 and the description already summarizes the return shape (function names with signatures/descriptions), and annotations cover safety, so the main gaps are the undocumented `limit` semantics and the absence of guidance on when to reach for this tool versus vw_exec_python. For a read-only lookup tool that is close to 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 0%, so the description must carry the load. The example queries ('record field', 'symbol insert', 'LDevice') usefully convey that `query` is a natural-language/keyword search over names and docs, but the `limit` parameter is left entirely unexplained in both schema and description.

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

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

States a specific verb (Search) and resource (the live vs.* API / built-in docs of the running Vectorworks) and gives three concrete example queries. This clearly separates it from the domain-action siblings like vw_insert_symbol or vw_get_record, which operate on objects rather than the scripting API surface.

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 examples imply how the tool is used (finding function names before scripting), but there is no explicit when-to-use or when-not-to-use statement, and no mention of its relationship to vw_exec_python, the sibling an agent would most plausibly pair it with. Usage is inferred rather than stated.

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