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

Annotations only declare the safety profile (readOnly=false, destructive=false, openWorld=false); the description adds substantive behavior beyond them: one undo step, results inherit the first target's class and attributes, tools are preserved unless keep_tools=False, and floating-point noise is snapped to exact input coordinates. These are exactly the side effects an agent needs before mutating geometry.

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 tool's domain and guarantees, then a compact per-operation glossary. Every clause conveys a distinct fact (arcs stay arcs, attribute inheritance, snapping, undo) 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?

For a six-parameter mutation tool with no output schema and thin annotations, the description covers what matters: what each operation produces, what happens to tools, whose attributes survive, and the undo granularity. The undocumented 'unit' parameter is the only loose end.

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 and mostly does: it explains the target/tool relationship, the split_line format [[x1,y1],[x2,y2]], and keep_tools semantics. Only 'unit' is left entirely undefined in both schema and description, which is the one remaining 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?

Names a specific operation family (exact 2D boolean/area operations on Vectorworks/Parasolid geometry) and enumerates all four modes with a concrete example ('a ring from its pieces'). This clearly separates it from siblings like vw2d_offset, vw2d_edit, and vw2d_transform, which do not combine areas.

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?

Each operation carries its own selection rule: union merges targets+tools into one area, subtract cuts tools out of each target, split requires split_line. That is strong guidance for choosing the right operation. It stops short of routing between this tool and siblings (e.g. when to use vw2d_offset or vw2d_edit instead), so it is not a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description is consistent with that. It adds genuine context beyond the annotations: the report plus a check image with numbered issues, the suggested fix action per issue, 0.005 mm precision, distances measured on true arcs, and the performance characteristic of bbox scoping. It does not say where/how the check image is produced or persisted.

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 outcome, then the detection list, then parameter guidance. Dense and nearly every clause earns its place for an 11-parameter tool, though the run-on 'Finds:' block and mixed issues/params material could be segmented more cleanly.

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 11 parameters and no output schema, the description does well to state the return shape and the core comparison/tolerance behavior. But it omits how the scoping parameters (layer, uuids, selection, class_name, image, max_issues) interact with the check, which an agent needs to scope a run 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 carries the full burden and does explain the hard parameters well: compare enum semantics (layer/class/all), an example for ignore_classes, the checks enum values, bbox scoping behavior, and tolerance_mm as the miss distance. However, image, layer, uuids, selection, class_name and max_issues are never mentioned, so several parameters remain 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?

Specific verb + resource ('Check drawing quality on the exact geometry') immediately followed by an enumerated list of what it detects, which makes it unmistakable against siblings like vw2d_fix or vw2d_structure. An agent can select this without opening the schema.

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

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

The description gives real routing guidance: compare modes for what to compare against, ignore_classes for intended overlaps, bbox for speed on large drawings, and 'each issue suggests a vw2d_fix action' pointing to the remediation sibling. It lacks an explicit 'use this instead of X when...' exclusion statement, so it stops short of a 5.

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

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

Annotations already carry destructiveHint=true and readOnlyHint=false, so the safety profile is known from structured data. The description adds genuinely new context, that the operation is restorable via vw_revert_last, but says nothing about cascading effects, whether restorability holds after other edits, 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?

One short sentence, front-loaded with the action and followed by the recovery hint; every clause carries information. It is arguably too terse for a destructive tool rather than padded.

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

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

With no output schema, no annotations gaps and no parameter documentation, the description needs to carry more weight. The restore hint is valuable, but an agent still cannot tell which objects are addressable by UUID or what state remains after deletion.

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

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

Schema description coverage is 0% and the description never mentions the sole parameter. It does not clarify that "objects" means the uuids array or where those UUIDs come from (e.g. vw2d_read, vw_find_objects), leaving an undocumented required array.

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

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

States a specific verb and resource ("Delete objects") so the agent immediately knows the effect. It does not distinguish itself from any sibling, but none of the siblings appear to be an alternative delete path, so ambiguity is low.

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 points to vw_revert_last as the recovery path, which implies this is the tool to use when a deletion may need undoing. There is no explicit statement of when to prefer it, prerequisites, or what happens if the objects have dependents.

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

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

The annotations already declare a non-readonly, non-destructive, closed-world operation, and the description adds meaningful behavior: all-or-nothing execution in one undo step, the class requirement unless allow_no_class=True, and returned exactness plus check issues. It does not contradict 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 long but largely justified by the nested item grammar, and it is front-loaded with the core purpose. The bullet structure is efficient, though some dense inline examples and missing separation between call-level parameters reduce clarity slightly.

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 drawing tool with no output schema, the description explains the return values (uuids, exactness, check issues) and class/attribute behavior well. It is nearly complete for invocation, but the missing usage guidance and unclear tolerance_mm/check semantics leave 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?

With 0% schema description coverage, the description carries most of the parameter burden and does so extensively for the complex items grammar, including geometry types, attributes, and per-item overrides. It also covers class_name, layer, attributes, unit, and allow_no_class, but leaves tolerance_mm and the exact role of check under-explained.

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

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

The description gives a specific verb and resource: drawing exact 2D objects with all-or-nothing behavior. It is clear what the tool creates, but it does not explicitly distinguish itself from related siblings such as vw2d_preview, vw2d_edit, or vw2d_transform.

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 describes the operation and atomic undo behavior but gives no explicit when-to-use or when-not-to-use guidance. It never names alternatives like vw2d_preview or explains conditions for choosing this tool over editing, transforming, or previewing geometry.

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 say readOnly=false/destructive=false; the description goes much further, disclosing the in-place vs rebuild fork, that uuid is preserved on in-place edits and a new uuid is returned on rebuild, that class/attributes/name/group/stacking survive a rebuild, and that the operation is one undo step. That is exactly the behavioral context an agent needs before calling 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?

The mutation behavior is front-loaded in the first sentence and the remaining clauses are all load-bearing, with zero filler. Dense but readable, sized appropriately for an 8-parameter geometry edit.

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-capable geometry rewrite with no output schema and no schema descriptions, the description covers the essential contract (input modes, identity/rebuild semantics, undo). The gaps are the unexplained unit, relative, and closed parameters, which an agent must guess at from the schema defaults alone.

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 8 parameters, so the description has to carry the load. It does well on the three geometry inputs (points as corner pairs, path matching vw2d_draw, vertices as [x, y, type, radius] from vw2d_read) and on holes, but says nothing about uuid, unit (which has an enum), closed, or relative, leaving half the 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?

Opens with a specific verb and resource: 'Replace the outline of a polygon/polyline/rect exactly.' An agent can tell this mutates an existing object's geometry rather than creating one. It never names a sibling such as vw2d_draw or vw2d_transform to sharpen the boundary, 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?

'Give one of: points, path or raw vertices' explains the mutually exclusive input modes and points at vw2d_draw paths and vw2d_read output as the canonical formats, which strongly implies edit-existing vs draw-new. But there is no explicit when-to-use statement and no exclusions (e.g. why choose this over vw2d_draw or vw2d_transform).

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

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

Annotations only declare the generic read/write/open-world profile; the description adds that the operation re-runs the check and consumes exactly one undo step, plus per-action consequences (top copy stays, priority keeps its area, no stacked fills, arcs keep their circle). Those are exactly the mutation semantics an agent cannot infer from the annotations.

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

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

Front-loaded with the one-line summary, then a terse definition list keyed by action – the right structure for a seven-mode tool with an enum. Every clause carries information (the parenthetical about stacked fills is the only borderline embellishment).

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 14-parameter mutation tool with no output schema and no schema descriptions, the description covers the domain-critical parameters but silently drops the scoping/selection parameters and `compare`, so an agent cannot construct a scoped call from the description alone. Adequate for the fix semantics, incomplete for scope 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 carry the parameter burden; it explains action semantics, tolerance_mm, fixed, share_vertices, merge_short, priority, issue_ids and uuids-in-merge well. However, six of fourteen parameters (selection, layer, class_name, compare, image, ignore_classes) are never mentioned anywhere, leaving a real 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 ('Fix check issues exactly, then check again') and ties itself to the sibling vw2d_check as the source of issues. Each of the seven actions is named and given a concrete effect, so an agent can tell this apart from vw2d_edit, vw2d_boolean and vw2d_check 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?

Per-action lines effectively say when each mode is appropriate (e.g. overlaps with vs without `priority`, merge for union into one area), and the closing sentence explains `issue_ids` scoping to the last vw2d_check. It never explicitly says when not to use this tool in favor of vw2d_edit or vw2d_boolean, so it stops short of 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?

The description adds important behavioral detail beyond the annotations: positive distance means outward for counter-clockwise outlines, and replace=True swaps the original for the result. The annotations already state the tool is not read-only and not open-world, and the description does not contradict them. It does not discuss reversibility or return behavior, but it is otherwise transparent.

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 two short sentences with no wasted language. The core operation and the replace behavior are 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?

Given five parameters, no output schema, and zero schema descriptions, the description is only partially complete. It covers the core offset semantics and replace behavior, but omits unit handling, smooth_corners meaning, and what is returned. Still, the annotations cover the safety profile and the main operation is understandable.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains distance direction and the replace flag, but says nothing about unit, uuid as the target object, or smooth_corners. Two of five parameters receive useful semantic context, leaving substantial gaps.

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

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

The description uses a specific verb and resource: offset a polygon/polyline outline by distance. It adds practical examples (wall thickness, plaster layer) and the direction convention. It does not explicitly differentiate from siblings such as vw2d_edit or vw2d_transform, so it falls short of a 5.

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

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

The examples 'wall thickness or a plaster layer' give clear context for when this tool is useful. It does not name alternatives or exclusions, but the intended usage is concrete rather than merely 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?

The description adds behavior annotations do not cover: the output is a rendered image, issues are shown in red and orange, arrows show where vw2d_fix would snap points, and bbox both limits the view and re-runs checks on that area. That last point is a non-obvious but important side effect. The return format and whether points are mutated are not stated; readOnlyHint covers that.

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 short and front-loads the render step, but the telegraphic style ('arrows = where vw2d_fix snap would move a point') and the run-on inventory of two parameters sit awkwardly together. The result is compact but cryptic rather than fully 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?

With 10 optional parameters, no output schema, and no annotation detail beyond read-only, the description is far too thin. Key knobs an agent must set (compare mode, width_px, selection, tolerance_mm, ignore_classes) are left unexplained, so calling this correctly requires guessing.

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% for 10 parameters, so the description has to explain them. It explains only focus_issue and bbox, and even for bbox it gives no units beyond 'document units' and no ordering convention. layer, uuids, compare, width_px, selection, class_name, tolerance_mm, and ignore_classes are never mentioned, so 8 of 10 parameters are 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?

The description uses a concrete verb and resource: it renders a preview image of the geometry with issues annotated. Color-coding and arrow semantics are stated. It does not, however, explicitly frame this as 'the preview counterpart to vw2d_check', so the differentiation from siblings stays 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?

Two usage scenarios are spelled out: focus_issue zooms to an issue id coming from vw2d_check, and bbox limits the preview to an area. That is real guidance, but it never says when to call this instead of vw2d_check on its own, or when a preview is unnecessary.

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 useful behavior about how grouped objects are returned (listed after their group with a 'parent' field) and that bbox clips the read to an area. However it never mentions the 'limit' parameter (default 2000) or what happens when results are truncated, which is the main behavioral risk for a bulk 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?

The purpose line is front-loaded, the scope follows, and the encoding details come last. Despite being dense, every clause (vertex type codes, hole handling, per-shape geometry layouts) conveys information an agent needs to interpret the result, and there is 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, the description correctly spends effort describing the shape of returned geometry per object type and the group/parent nesting, which is valuable. But it omits the limit/truncation behavior and the include_geometry toggle, leaving an agent unable to predict result size or the effect of an available 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 coverage is 0%, so the description must carry the load, and it gives meaning to uuids, selection, layer (including the '*' wildcard), class_name, and bbox (ordering [x1, y1, x2, y2]). Two of seven parameters — limit and include_geometry — are left completely unexplained, which is why this is not a 5.

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

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

Opens with a specific verb+resource: 'Read 2D objects with their exact geometry and attributes.' The scope sentence makes clear it can be driven by uuids, selection, layer, or class filter, which distinguishes it from a plain finder like vw_find_objects. It never names a sibling explicitly, so a 5 is not warranted.

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

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

Lists the four ways to scope a read (uuids / selection=True / layer / class_name) and states the default ('the active layer'), which is real selection guidance. It does not say when to prefer this over vw_get_selection or vw_find_objects, even though selection=True clearly overlaps with them, and there are no explicit 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=true and openWorldHint=false, so safety is covered. The description adds a genuinely non-obvious note that default Vectorworks content is included and imported automatically when used, but it says nothing about result ordering, limit behavior, or whether listing defaults has any side effect on the 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?

Two compact sentences, front-loaded with the resource enumeration before the filter note. The nested parenthetical about default content is slightly awkward but 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?

With four parameters, one required, and an output schema present, the description covers the core selection logic but omits `limit` semantics and any routing versus the overlapping layer/class listers. Adequate to call correctly, 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 compensate; it does for `query` (substring matching with concrete examples) and partly for `include_defaults` via the 'document + Vectorworks default content' phrasing, and the resource list maps onto `kind`. The `limit` parameter (default 200) is never explained in either place, leaving a real 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 four resources it covers (hatches, line types, classes, layers), matching the `kind` enum exactly. However, it does not distinguish itself from siblings vw_list_layers and vw_list_classes, which appear to cover two of the same resources, so an agent cannot tell which 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?

The only guidance given is how the `query` substring filter behaves, with examples ("Beton", "ISO-02"). There is no statement of when to use this tool versus vw_list_layers, vw_list_classes, or vw2d_structure, 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 readOnlyHint=true, so the agent knows this is not a data mutation, and the description usefully adds that the viewport zooms by default. However, it does not say whether the selection replaces the existing selection, what happens with invalid or empty uuids, or whether the zoom is animated/blocking, which are the meaningful behavioral facts for a UI manipulation tool.

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

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

A single front-loaded sentence with no filler; the action and its effect are stated immediately. It is efficient but slightly too terse given the parameter ambiguity.

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 two-parameter tool with no output schema this is minimally adequate: the read-only safety profile comes from annotations and the zoom side effect is noted. It is still incomplete on uuid sourcing/format and on whether the call replaces or augments the current selection.

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 full burden: it only hints at the 'zoom' parameter ('and zoom to them') and says nothing about what 'uuids' should contain or where they come from. Neither parameter's default (zoom=true) or format is explained.

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 ('Select') and resource ('objects in Vectorworks'), plus an additional side effect (zoom to them), which differentiates it from read-only siblings like vw_get_selection. It stops short of explicitly naming the sibling it is not, so it does not reach 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?

The clause 'so the user sees what was drawn or changed' implies a post-draw/post-edit usage context, but the description never states when to prefer this over vw_get_selection or vw_find_objects, nor any prerequisites such as needing valid uuids.

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 adds useful behavioral context beyond the annotations: class_name creates the class if missing, changes are 'One undo step,' and by_class is recommended for consistency. It does not discuss permissions or failure modes, but it covers the key 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?

The description is compact, front-loaded with the core action, and each sentence provides essential information about parameter behavior or side effects.

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 lack of an output schema and the presence of annotations, the description is nearly complete: it covers mutation behavior, undo, and most parameter details. The omission of `uuids` is the main missing piece for full correctness.

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 compensate. It thoroughly documents `class_name`, `layer`, and especially `attributes` with accepted values and formats, but it completely omits the required `uuids` parameter, leaving a significant gap.

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

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

The description states a specific verb and resource: 'Change class, layer or graphic attributes of objects.' It clearly distinguishes the operation from generic editing siblings, though it does not explicitly name an alternative tool to contrast 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?

Usage is implied by the purpose, and some guidance is given for attribute values (e.g., `{"by_class": true}` is 'recommended'). However, there is no explicit guidance on when to use this tool versus siblings like `vw2d_edit` or `vw2d_transform`, nor any 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 non-read-only, non-destructive, closed-world, so safety is covered. The description adds real semantics beyond that: existing classes keep their name and given attributes are applied (a merge, not a replace), and the template is gated on document state and user consent. It still omits what happens to attributes not supplied and whether layers are likewise merged or replaced.

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

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

Purpose is front-loaded, and the JSON-shaped examples earn their space because the schema itself is opaque. Density is high with no filler sentences, though the inline example formatting is a bit hard to parse and the attribute list could be structured 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 5-parameter mutation tool with no output schema, the description covers the two substantive parameters in depth, states the merge behavior for existing classes, and constrains the template. Missing pieces are the two active_* parameters and any statement of what is returned or how failures (e.g. unknown layer) are reported.

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 every array item is an untyped object with additionalProperties:true, so the description is doing heavy lifting: it spells out the class attribute keys (pen, fill, hatch, line_weight in mm, line_style, opacity), the '-' hierarchy convention, and the layer shape ({name, scale}). The gap is active_class and active_layer, which appear nowhere in the description and are unguessable from 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 opening sentence states a specific verb pair and resource: create or update classes and design layers, and ties it to the outcome (organised drawings). This clearly separates it from read-side siblings like vw_list_classes / vw_list_layers. It does not explicitly distinguish itself from vw2d_set_attributes, which also touches class attributes, so it falls short of a 5.

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

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

There is one genuine conditional guideline: use template "architektur" only if the document has no class standard yet and the user agrees — that is real when/when-not guidance. However, nothing tells the agent when to call this versus vw2d_set_attributes, vw_list_classes, or vw2d_structure, and no prerequisite (e.g. inspect existing classes first) is stated. Usage is mostly implied by the field examples.

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 readOnlyHint already declares safety, and the description adds substantive behavioral detail about what is inspected: none-class objects, unused classes, empty layers, by-class violations, misplaced dimensions/texts, and inconsistent layer scales. It does not describe output format or scope limits, but it goes well beyond the annotations.

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

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

The description is dense but front-loaded with the core resource and then enumerates diagnostic categories. The parenthetical list is long, but every item adds concrete meaning; the single usage sentence is also purposeful.

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 diagnostic tool, the description gives enough detail about what categories of information and problems it reports. It could specify scope (e.g., active document) or output shape, but an agent can confidently call it based on the current text.

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

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

The tool has zero parameters, so there are no parameter semantics to explain; the baseline for a no-parameter tool is 4. The description correctly does not waste space discussing nonexistent inputs.

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 the specific resource analyzed: document layers and classes, including object/class membership, class attributes, and organization problems. It clearly distinguishes itself from simple list tools like vw_list_layers and vw_list_classes by focusing on structural diagnostics, though it lacks an explicit leading verb such as 'analyze' or '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?

It gives a clear usage context: 'Read this before drawing so new objects follow the document's structure.' That tells the agent when to call it, but it does not mention alternatives or when not to use 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 declare readOnlyHint=false with destructiveHint=false; the description adds non-obvious behavior beyond that: 'copy=True keeps the originals' and 'One undo step', which tells the agent the operation is reversible in a single step. It doesn't say what happens when required params for a chosen operation are omitted (a likely error path).

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

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

Front-loaded with the one-line purpose, then compact per-operation lines with zero filler. The telegraphic style ('scale: center + sx (+ sy)') is dense to the point of needing careful parsing, but 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 13-parameter mutation tool with no output schema and no annotation detail, the description supplies the operational contract an agent needs to form a valid call. Remaining gaps are 'unit' semantics and what is returned when copy=True (new object ids vs. originals).

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 carries the whole burden and largely delivers: it maps operation to parameters (dx/dy or from_point+to_point for move, center+angle in degrees ccw for rotate, axis as [[x1,y1],[x2,y2]] for mirror, center+sx(+sy) for scale). Only 'unit' is left unexplained, which is a small residual gap given the near-total coverage of 11 of 13 parameters.

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

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

Opens with a specific verb set and resource: 'Move, rotate, mirror or scale objects', with the copy flag's effect stated inline. An agent can immediately tell this is the geometric-modification tool and distinguish it from vw2d_offset (offsetting) or vw2d_edit (general edits).

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

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

Gives concrete invocation guidance per operation, including the 'from_point -> to_point (exact difference, e.g. a corner onto another object's corner)' idiom that tells the agent when to prefer it over dx/dy. It does not name a sibling alternative or state exclusions (e.g. vs. vw2d_offset or vw2d_edit), which keeps it below a 5.

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

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

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

Adds substantial context beyond the annotations: what gets deleted vs restored, that restoration covers geometry, attributes, class, name, group and stacking position, that UUIDs change, and why repeated calls behave differently from Cmd-Z. One caveat: destructiveHint=false while the description says it deletes created objects — the description covers this by framing everything as a restore of prior state, so it is disclosed rather than contradicted.

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

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

Front-loaded with the core action in the first clause, followed by tightly packed but non-redundant qualifiers. Every sentence adds a distinct operational fact (repeat behavior, Cmd-Z difference, exec_python exclusion, UUID change).

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?

No output schema exists, and the description does gesture at the return value ('new UUIDs returned in mapping'), which is enough to set expectations though the shape of that mapping is left vague. Scope, limits and caveats are otherwise fully covered for a zero-parameter 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?

Zero parameters, so the baseline is 4. The description adds no parameter detail because there is none to add; the 'mapping' mention concerns the return value, not inputs.

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 scope: 'Undo exactly the last MCP write in the active document', then enumerates what that means (deletes created objects, restores changed/deleted ones, restores record fields). It also explicitly separates itself from raw vw_exec_python edits, which no sibling list entry 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?

Gives clear invocation guidance ('call repeatedly to step further back') and an explicit exclusion (raw vw_exec_python edits can't be reverted this way). It stops short of naming a full alternative workflow for non-MCP changes, so not a 5.

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

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

Annotations already 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.