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

Annotations only declare readOnlyHint=false, so the description carries most of the burden and does it well: it discloses the side-effects (saves document, writes artifact file and manifest to disk) and a prerequisite (require a clean persisted state). Missing only failure/reversibility details, so a strong 4.

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

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

Front-loads the core action and uses labeled sections (Side-effects, Disambiguation) for structure. Dense jargon like 'content-addressed accepted artifact' costs a little clarity but every sentence earns its place.

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

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

With an output schema present and 100% param coverage, the description supplies the prerequisite and side-effect context an agent needs. It leaves out error/rollback semantics but is otherwise complete for a single-param operation.

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

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

Schema coverage is 100% with a single optional destination_dir already documented in the schema, so baseline is 3. The description adds no extra syntax, default behavior, or directory semantics beyond what the schema states.

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 specific compound verbs and resources (save drawing, copy to content-addressed accepted artifact, write SHA-256 manifest) and clearly differs from siblings like document_save or document_save_as by adding provenance artifact creation. An agent can distinguish it from the raw save tools immediately.

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 says 'Use at completion of milestone or deliverable handoff,' giving clear triggering context. It stops short of naming when NOT to use it or pointing to the sibling (e.g. document_save) for ordinary saves, so not a full 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?

The only annotation is readOnlyHint=false, so the description carries most of the behavioral burden. It usefully discloses side effects, active-space creation, idle yields, and predecessor fingerprint binding, but it does not state atomicity or what happens if expected_parent_fp mismatches or if only some entities fail.

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 short, front-loaded, and cleanly segmented into purpose, side effects, and disambiguation. Every sentence adds useful selection or invocation context.

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 full schema descriptions and an output schema present, the definition gives enough context for selection and invocation. The remaining gap is failure semantics for a batch mutation, particularly partial-failure behavior and fingerprint mismatch handling.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics by stating the 1..10000 batch limit and framing document_pid plus expected_parent_fp as caller-supplied binding 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 a specific verb and resource: creating 1..10000 generic typed CAD primitives. It also explicitly distinguishes the tool from entity_create_* for single-entity creation, so an agent can route correctly without inspecting sibling schemas.

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

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

It gives clear when-to-use guidance: high-throughput batch primitive creation. It also names the alternative for single entities, entity_create_*, making the selection rule 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?

The description discloses the mutation side effect ('Inserts block references across the drawing') and the optimistic-locking precondition, which go beyond readOnlyHint=false. It does not describe atomicity, partial failure behavior, or required transaction context for a potentially large batch, so it is strong but not complete.

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 definition is front-loaded with the core action and precondition, then gives side effects and disambiguation in compact labelled lines. Every sentence adds useful information with no repetition.

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

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

For a mutating batch tool with an output schema present, the description covers purpose, precondition, side effects, and alternative. It leaves out batch atomicity and failure semantics, which would be useful given it can insert up to 10000 objects, but the essential call guidance is present.

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 already 100%, so the schema documents each parameter. The description adds useful semantic context by noting the quantity bound, persistent-PID binding, and that document PID and predecessor fingerprint must still match for the insert to proceed.

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 ('Insert ... block references') and adds precise scope: 1..10000, persistent-PID-bound, through the managed native bridge. It also distinguishes the tool from block_insert, so an agent can identify it 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?

It explicitly routes the agent: use for bulk component placement, and use block_insert for single placement. It also gives a concrete precondition, matching caller document PID and predecessor fingerprint, making when-to-use clear.

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

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

Annotations only declare readOnlyHint=false, so the description carries the real burden and does disclose the mutation side-effect ('Mutates entity transforms in active drawing') plus the optimistic-locking requirement. It stops short of stating what happens on fingerprint mismatch (abort vs partial apply) or whether the batch is atomic, which matters for a 10k-entity write.

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 labeled lines, each earning its place: operation+scope, side-effects, disambiguation. Front-loaded with the verb and the limit, no filler or restatement of the name.

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

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

Output schema exists, so return values need no explanation. Given that, the description covers the operation, the scope bound, the mutation warning, the locking precondition, and the sibling alternatives — everything needed to select and invoke it correctly. Only the failure semantics of a fingerprint mismatch remain unstated, a minor gap for this complexity level.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: the 1..10000 cardinality bound on semantic_pids and the framing of document_pid + expected_parent_fp as a joint binding precondition. The 'typed translate/rotate-Z/uniform scale' phrasing also constrains the free-form transform object that the schema leaves as additionalProperties.

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 (Transform), a specific resource (persistent semantic PIDs), the cardinality bound (1..10000), and the three supported transform types. The Disambiguation line explicitly names the single-object siblings it is not, so the tool is separable from object_move/object_rotate/object_scale 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?

Explicit when-to-use (bulk updates to existing entities) and explicit alternative routing (single objects -> object_move, object_rotate, object_scale). The document PID and fingerprint binding prerequisites are stated up front rather than left for the agent to discover at call time.

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?

Annotation coverage is thin (readOnlyHint=false only), but the description carries meaningful weight itself: it discloses that this is a copy-based mutation and that source objects remain in their original space, which an agent could not infer from the annotations. It does not state behavior on duplicate names or error conditions, keeping it at a 4.

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

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

Three short, front-loaded lines with labeled side-effects and disambiguation, easy to scan. Minor waste: the source-objects persistence is stated twice, once in the first sentence and again in the side-effects line.

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

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

An output schema exists, so return values need no explanation, and required parameters plus defaults are covered by the schema. The description covers the mutation's key consequence (originals retained) but omits failure behavior such as name collisions on a 'unique block definition name'.

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

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

Schema description coverage is 100%, so all four parameters (name, base_x, base_y, object_ids) are already fully documented with defaults and units. The description only restates that objects are copied and a WCS base point is used, adding no semantics beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Create a named block definition by copying the specified existing objects around a WCS base point') and adds a scope detail about the source objects. The disambiguation line explicitly separates it from inserting an instance, which is the main confusable sibling (block_insert).

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 disambiguation line clearly frames the choice: this tool creates a reusable definition and does not insert an instance, implicitly routing instance placement to block_insert. There is no explicit 'use when' clause or prerequisite note, so it falls just 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?

With only readOnlyHint=false for annotations, the description usefully discloses the side-effect (adds an INSERT entity to active space) and the default-layer fallback. It does not mention transaction/undo interaction or failure modes for a missing block definition, so it is strong but not exhaustive.

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 labeled lines – core action first, then Side-effects and Disambiguation. Every sentence carries distinct information and nothing is repeated.

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

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

Output schema exists, so return values need no explanation, and the mutation semantics plus sibling routing are covered. Missing only error/validation behavior (e.g., nonexistent block name) to be fully complete for a write tool.

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

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

Schema coverage is 100%, so all seven parameters are already documented, including units and defaults. The description restates rotation in degrees and XY scale but adds no syntax or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Insert), resource (existing named block), and key parameters (WCS point, XY scale, rotation in degrees, optional layer). It is immediately distinguishable from batch_insert_blocks and from block_create/block_list siblings.

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 the agent: 'use batch_insert_blocks for bulk placement' names both the alternative and the selecting condition. It does not cover prerequisites such as the block needing to already exist in the drawing, but the usage context is clear.

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

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

The description reinforces the read-only annotation by stating 'Side-effects: None' and adds useful scope behavior by excluding anonymous blocks. It does not elaborate on pagination or performance, but with readOnlyHint already covering safety, the added behavioral context is solid.

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 front-loaded with the core operation, then efficiently adds side-effect and disambiguation notes. Every sentence contributes useful information without repetition.

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

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

For a read-only list tool with full schema coverage, readOnlyHint, and an output schema, the description covers purpose, scope, side effects, and usage context. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents limit, offset, name_filter, include_xrefs, and include_xref_dependent. The description does not add parameter-level detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

The description uses a specific verb and resource: list named block definitions, excluding anonymous blocks. It also states the returned fields, so an agent can distinguish this from block creation/insertion and xref-specific 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?

It gives a clear usage context: discover available blocks before inserting. It does not explicitly name alternatives or when-not-to-use cases, but the guidance is sufficient for routing relative to block_insert and batch_insert_blocks.

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 readOnlyHint=false, so the description carries most of the load and does add value: it discloses the side-effect (a DIMENSION entity is added) and the dependency on the active dimension style. It stops short of noting reversibility/undo or transactional requirements, which matters for a mutating drawing tool.

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

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

Three short, labeled lines with the action front-loaded and no filler. Side-effects and disambiguation are broken out where the agent can find them immediately.

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

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

An output schema exists, so return values need not be described, and the mutation plus style/layer defaults are covered. Minor gap: no note on how the created entity is identified or whether it participates in the active transaction.

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

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

Schema description coverage is 100%, so the schema already explains each coordinate as a WCS point. The description reinforces WCS and the active-style behavior but adds no syntax or constraint detail beyond the schema; baseline 3 applies.

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

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

States a specific verb+resource ('Create an aligned dimension') and the exact inputs it consumes (WCS extension points plus a dimension-line point). The disambiguation line gestures at how it differs from other dimension tools, though it describes the geometric outcome rather than naming dimension_linear as the alternative.

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

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

Implies usage through 'using the active drawing's dimension style' and the layer default, but never says when to pick this over dimension_linear, dimension_angular, or dimension_ordinate. The agent must infer the choice from the geometry description alone.

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

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

Beyond the readOnlyHint=false annotation, the description discloses that a DIMENSION entity is added (mutation side-effect) and that invalid collinear rays are rejected before mutation — valuable pre-execution context. It stops short of noting layer fallback behavior or return shape, but the mutation semantics and validation contract are well covered.

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, followed by a compact side-effect line and a disambiguation line. Zero filler; every clause conveys 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?

Covers the action, the geometric inputs, validation behavior, and the mutation side-effect, and an output schema exists so return values need not be described. Complete enough for correct invocation; minor omissions like layer default handling are already in the schema.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description reinforces the geometric roles of vertex/rays/text point and their WCS nature, but adds little beyond what the schema provides — baseline 3 is appropriate.

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

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

States a specific verb+resource ('Create a typed angular dimension') and enumerates the geometry inputs (vertex, two WCS ray points, text point). The word 'angular' plus the geometric phrasing clearly separates it from dimension_linear, dimension_aligned, dimension_radial, dimension_diametric, and dimension_ordinate siblings.

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

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

'Use to dimension angles in degrees' gives a clear usage context, and 'rays must not be collinear' is an explicit precondition that guides invocation. It does not name a sibling alternative explicitly, but the angular-vs-other-dimension distinction is unambiguous from the name and description.

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

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

Annotations only declare readOnlyHint=false; the description adds real value by stating the side-effect ('Adds diametric DIMENSION entity'), that the active dimension style is used, and that leader length must be positive. Missing only return/error behavior, which the output schema partly covers.

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

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

Three short, front-loaded lines: purpose first, then side-effects, then disambiguation. No filler, and each line adds distinct information.

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

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

With an output schema present and annotations covering the mutation flag, the description supplies the remaining essentials: side effect, style source, and sibling routing. Only minor gaps around failure modes and required drawing context remain.

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

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

Schema coverage is 100%, so the baseline is 3; the description nudges above it by clarifying the geometry model (center/chord pair defining the diameter) and the 'positive' constraint on leader_length that the schema does not state. Layer defaulting is left to the schema, which is fine.

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

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

States a specific verb and resource ('Create a typed diametric dimension') plus the geometry inputs (center/chord, leader length) and the style source. It also explicitly separates itself from dimension_radial, so an agent can distinguish it from the radial sibling without opening schemas.

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

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

The disambiguation line gives a concrete routing rule: use this for diameter display, use dimension_radial for arc radii. That is clear context-setting, though it does not state broader preconditions (e.g., an active drawing must exist, dimension style must be configured).

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 give readOnlyHint=false, so the description correctly discloses the mutation side-effect ('Adds linear DIMENSION entity'), which is the key context an agent needs before committing a write. It also clarifies unit conventions (degrees for rotation, drawing units for placement). It does not cover layer-targeting behavior or whether the new entity is returned/selected, so it stops short of full transparency.

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, labeled sentences: purpose, side-effects, disambiguation. The single most decision-relevant fact (this is a write that creates an entity) and the routing rule are both front-loaded with zero filler.

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

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

An output schema exists, so return-shape explanation is unnecessary, and annotations plus the side-effects line cover the safety profile. For an 8-parameter creation tool the description supplies the disambiguation and unit semantics an agent needs; minor gaps (layer fallback behavior, what the created handle looks like in practice) are already handled by schema defaults.

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

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

Schema description coverage is 100%, so every parameter is already documented in structured form and the baseline is 3. The description reinforces meaning (WCS coordinates, degrees for rotation, drawing units for placement) but adds no syntax, constraints, or defaults beyond what the schema already states.

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

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

States a specific verb and resource ('Create a linear dimension') and immediately identifies the geometric inputs (WCS extension points and dimension-line point) plus the rotation/placement conventions. Combined with the explicit disambiguation line, an agent can distinguish it from dimension_aligned, dimension_ordinate, etc. without reading schemas.

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

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

The Disambiguation line explicitly states when to use this tool (orthogonal 0/90 deg dimensions) and names the sibling to use instead for angled geometry (dimension_aligned). That is exactly the when/when-not/alternative pattern.

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 readOnlyHint=false, so the description carries real weight here and delivers: 'Adds ordinate DIMENSION entity' makes the mutation explicit and consistent with the annotation, and 'strict axis validation' warns that invalid axis values will fail rather than silently default. It omits whether changes are undoable, which layer/space the entity lands in, and any transaction requirement.

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 labeled lines: the action first, then side-effects, then disambiguation. Zero filler and the mutation warning is not 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?

With full schema coverage, an output schema, and readOnlyHint annotation present, the description covers the essentials an agent needs to call it. It stops short on operational context: whether an active document/transaction is required and what happens to the entity's default dimension style.

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

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

Schema description coverage is 100%, so all six parameters are already documented (axis default 'x', layer default null, the four coordinate pairs), establishing a baseline of 3. The description adds only conceptual mapping of definition point and leader endpoint plus the promise of strict axis validation, but gives no new syntax, valid ranges, or layer behavior beyond 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?

Specific verb and resource: 'Create an X- or Y-ordinate dimension' plus the inputs it is built from (WCS definition point and leader endpoint). It is specific enough that an agent can distinguish it from linear/aligned/angular dimension siblings by resource type, but it never names or contrasts those siblings explicitly, 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?

'Measures absolute distance from drawing origin or datum' implies the use case (ordinate/datum dimensioning) and 'strict axis validation' implies a constraint on the axis argument, but there is no explicit when-to-use versus dimension_linear/dimension_aligned, nor stated prerequisites such as requiring an active document or open transaction. Usage is inferable rather than stated.

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

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

Annotations only declare readOnlyHint=false, so the description must carry the behavioral load, and it does disclose the side effect explicitly: 'Adds radial DIMENSION entity.' The 'positive leader length' phrasing also flags an input constraint the schema does not enforce. It leaves out failure modes and whether a transaction is required for the addition to persist.

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 labeled lines with the operation stated first, then side effects, then disambiguation. Every sentence carries distinct information and nothing is repeated from the schema.

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

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

With an output schema present, return values need not be explained, and all six params are documented in the schema. What remains unaddressed is whether the arc/circle must already exist and whether the mutation needs transaction_commit to persist — useful given the surrounding transaction tools.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: 'center/chord geometry' groups the four coordinate params conceptually, and 'positive leader length' supplies a sign constraint absent from the schema's bare 'number' type. Layer/active-layer behavior remains schema-only.

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

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

States a specific verb and resource (create a typed radial dimension) plus the exact input geometry (center/chord, leader length) and the style source (active drawing dimension style). It explicitly distinguishes itself from the sibling dimension_diametric, so an agent can choose without opening either schema.

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

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

The disambiguation line gives an explicit alternative and the condition that selects it: use dimension_diametric for full circles, since this tool displays radius (R). It stops short of stating prerequisites (an existing arc/circle), and 'prefer' is a soft routing rule, but the core when-to-use guidance is present.

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 'Side-effects' line names the actual system variables mutated (INSUNITS, MEASUREMENT, LUNITS, LUPREC), which is real behavioral value beyond the readOnlyHint=false annotation. It does not state reversibility, whether omissions reset values, or any permission requirements, so there is still a gap for a mutation tool.

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

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

Front-loaded with the action and covered fields, followed by compact side-effect and disambiguation lines. The phrase 'using a bounded typed schema' is mild filler that does not earn its place, preventing a perfect score.

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

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

An output schema exists so return values need no explanation, and the side-effects line covers the main behavioral risk. What is missing is what happens when all four optional parameters are omitted (no-op or reset to defaults), a meaningful detail for a tool where every parameter defaults to null.

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

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

Schema description coverage is 100%, so each parameter's meaning and accepted values are already documented, establishing the baseline of 3. The description only restates the parameter categories and adds the meta remark 'bounded typed schema', giving no extra syntax, interaction, or default behavior information.

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 ('Configure') plus the exact resource set (drawing insertion units, measurement system, linear format, precision). No sibling tool touches unit configuration, so an agent can immediately tell this is the setup tool for units without consulting 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?

Explicitly says to 'Use during drawing setup to guarantee unit consistency (e.g. millimeters)', which gives a clear usage context and intent. It stops short of stating when NOT to use it or naming any alternative (e.g. object_set_properties for per-object overrides), so it falls just below the top mark.

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 the description's 'Side-effects: None. Read-only dependency audit' largely restates that. The added value is modest: it confirms the audit covers XREFs and images and reports resolution/load/completeness state, but no permission, performance, or failure-mode context is given.

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

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

Three short, front-loaded lines: purpose, side-effects, disambiguation. Efficient overall, though the side-effects sentence duplicates the readOnlyHint annotation and could be dropped.

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

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

With an output schema present and no parameters, the description needs only purpose, scope, and routing. It covers all three; the only shortfall is that it does not explicitly contrast with xref_list or drawing_audit for an agent choosing among them.

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 schema carries nothing to explain. The description correctly frames the operation as acting on the 'active drawing' implicitly, which is the only scope detail an agent needs.

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 (Inspect) and resource (external-reference dependencies for the active drawing), plus the reported facets: contained, resolved, loaded, completeness. It is clear what the tool does, but it never names its closest sibling (xref_list) to draw the line explicitly.

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

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

The disambiguation line gives a concrete usage condition: audit required file dependencies before archiving or sealing. That is a clear 'when', though it offers no explicit 'when not' or named alternative such as xref_list or drawing_audit.

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 readOnlyHint=false; the description goes further by naming the concrete side effect (writes a PDF artifact to disk) and the environmental prerequisite (may require live AutoCAD plotting capability), which materially affects whether the call will succeed. It also flags that the path must be 'allowed', signaling a path policy check before invocation.

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 labeled segments — core action, side effect, disambiguation — with the action front-loaded and zero filler. Every sentence carries a distinct piece of decision-relevant 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?

Output schema exists so return values need no explanation, and schema coverage handles parameters; what remains for the description — write side effect, plotting dependency, path restriction, and sibling routing — is all present. Nothing needed to invoke it correctly is missing, aside from overwrite behavior, which is a minor omission.

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

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

Schema description coverage is 100%, so both 'path' and 'layout' are already documented, including the default-to-active behavior. The description's phrase 'selected layout' echoes rather than extends the schema, so this is the baseline-3 case where structured fields do the work.

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

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

States a specific verb (Export) plus resource (active document or selected layout) and the output format (PDF), which is exactly what the name promises. The disambiguation line separates it from the raster sibling view_screenshot, so an agent can pick between them without inspecting either schema.

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

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

Explicitly names the alternative (view_screenshot) and the condition that selects it (quick raster inspection vs. vector deliverable export). This is the when-to-use-this-versus-that guidance most definitions omit.

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 annotation already establishes that this is a safe read operation, and the description reinforces that with 'Side-effects: None' and 'Read-only document query.' It adds some useful context such as 'verified' metadata and fields being returned 'when available,' but does not disclose failure modes or other behavioral details 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 three short, front-loaded sentences with no wasted text. It separates purpose, side effects, and disambiguation 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?

For a zero-parameter read-only query with an output schema and readOnlyHint annotation, the description provides enough context: what is read, from which document, which fields are included, and how it relates to other document queries. Nothing essential for correct invocation 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?

This tool has zero parameters, so there are no parameter semantics to explain. The baseline score of 4 applies because the description does not need to compensate for an input 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 states a specific verb and resource: reading verified metadata for the active document. It also lists the exact metadata fields returned and calls itself the primary document query tool, making its role distinguishable from broad siblings.

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: use this as the primary tool for inspecting active file state. It does not name when not to use it or explicitly compare with alternatives such as metadata_get, so it falls short of full alternative 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 only declare readOnlyHint=false, so the description adds real value: it discloses side-effects (changes the active session, produces an unsaved drawing) and a precondition behavior ('refuses unsafe transaction state'). It does not say what the failure mode returns or whether the previous active document is preserved, but the disclosure goes well beyond the annotation.

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 labeled lines: purpose, side-effects, disambiguation. Front-loaded with the verb+resource and no filler sentence anywhere.

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

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

An output schema exists so return values need not be explained, and with zero parameters the only remaining burdens are side-effects and the alternative, both of which are covered. Nothing an agent needs before calling 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 zero parameters, so there is no parameter semantics to explain; the baseline for a 0-param schema applies. The description correctly doesn't invent 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 specific verb and resource ('Create a new active CAD document'), plus scope ('in the current backend session'). It also names the sibling it is not (document_open), so an agent can distinguish it without opening either schema.

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

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

The Disambiguation line explicitly gives the selection rule: use this to start a clean drawing, use document_open to load existing DWG/DXF files. That is an when-to-use plus a named alternative, leaving nothing to inference.

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

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

The description adds a side-effects line and a disambiguation line beyond the readOnlyHint=false annotation, making clear this mutates session state rather than the file system. It does not cover failure modes (nonexistent path, blocked file, what 'allowed' means), which is a gap for a state-changing tool but not a contradiction.

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 main clause followed by compact side-effect and disambiguation lines; every line is labeled and scannable. Minor redundancy between 'changes session state' and 'Side-effects: Changes active document session' costs a point.

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

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

An output schema exists, so return values need no explanation, and the one parameter is fully schema-documented. The only unresolved item is the undefined 'allowed' qualifier, which an agent may not be able to evaluate before calling.

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

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

Schema description coverage is 100% and the single path parameter is documented as a 'Filesystem path to the existing DWG or DXF file to open'. The description adds only the implicit constraint that the file must already exist and be 'allowed', but does not define that constraint. Baseline 3 applies.

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

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

States a specific verb and resource — 'Open an existing allowed DWG/DXF path as the active document' — and scopes it to two file types. An agent knows exactly what the tool does 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 disambiguation line explicitly contrasts it with document_new ('use document_new to create a blank drawing'), covering both when to use this tool and when to use the sibling instead. Nothing is left to inference.

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

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

Annotations only supply readOnlyHint=false, so the description carries real weight and it delivers: it discloses the side-effect (unsaved drawing changes persisted to disk, dirty state cleared), the precondition (path must be a verified existing path), and a success criterion (persisted-clean readback). It stops short of saying what happens on failure (e.g. whether dirty state remains or an error is raised when the bound path is stale), which keeps it from a 5.

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

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

Three compact lines, each with a distinct job: core behavior front-loaded, then side-effects, then disambiguation. No filler or repetition of structured fields.

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 mutation tool with only a readOnlyHint annotation, the definition covers purpose, precondition, side-effect, success criterion, and sibling routing. An output schema exists, so return values need not be described, and nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% and the single parameter is well documented, so the baseline is 3. The description adds beyond the schema by explaining that supplying path re-routes behavior to SaveAs and that omission saves in-place against the currently bound path, which is a behavioral consequence rather than a restatement of the schema text.

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

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

States a specific verb and resource ('Save the currently bound document') plus the exact scope: in-place save to a verified existing path, with delegation to SaveAs when a path is given. The sibling document_save_as is named and differentiated, so an agent can pick between them without opening either schema.

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

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

The Disambiguation line gives an explicit routing rule: use document_save to persist in-place, use document_save_as to write to a new destination. The optional path parameter's effect ('delegate to SaveAs when path is supplied') reinforces the same rule from the parameter side.

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 readOnlyHint=false, so the description carries the behavioral burden and does so with a Side-effects section: writes to a new file path, verifies the bound path and persisted-clean state, and updates document scope. It stops short of covering error/permission behavior or what happens on an invalid destination, but the core mutation traits are disclosed.

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 save action, then uses labeled Side-effects and Disambiguation sections that each earn their place. Slightly dense phrasing ('verify the same bound path and immediate persisted-clean state') but no filler sentences.

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 unnecessary, and the description covers the mutation, side-effects, and sibling distinction. What remains missing is failure-mode behavior for a disallowed path, a minor gap for a write tool with minimal annotations.

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?

Only one parameter, and the schema already documents it at 100% coverage, including the .dwg/.dxf constraint. The description reinforces 'allowed DWG/DXF destination' but adds no syntax or validation nuance beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb (save) plus resource (active document) with the 'as' semantics (new DWG/DXF destination) clearly conveyed. It explicitly differentiates itself from document_save, so an agent can route between them without opening either schema.

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

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

The Disambiguation line names both when to use this tool ('fork or save under a new name') and the alternative ('document_save for in-place save'). Usage conditions and exclusions are 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?

Beyond the single readOnlyHint=false annotation, the description discloses the concrete side-effect (fixes corrupted entity pointers) and a meaningful output limitation: no machine-readable repair count is exposed. This directly helps an agent interpret results and understand the operation mutates the drawing.

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, labeled clauses (purpose, side-effects, disambiguation) with the core action front-loaded. Every sentence adds information and nothing is redundant.

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

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

With no parameters, full schema coverage, an output schema, and only a single annotation, the description supplies everything needed to invoke it correctly, including the caveat about repair counts. Minor gaps remain (e.g., behavior on failure or reversibility), keeping it just short of perfect.

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 description carries no parameter-documentation burden; baseline of 4 applies. Nothing about calling semantics is obscured.

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: running the backend drawing-audit on the active document, and clarifies that it maps to the live AutoCAD AUDIT command. It explicitly names a sibling (drawing_purge) to distinguish the operation, so an agent can choose it without opening other tools' schemas.

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

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

Gives an explicit trigger ('use after heavy edits or imports') and a named alternative with a contrasting purpose ('use drawing_purge to remove unused definitions'). The when-to-use and when-to-use-something-else are both spelled out.

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

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

readOnlyHint=true already covers the no-mutation profile, but the description adds value annotations can't: 'Side-effects: None', 'Read-only bounding box query', and specifically that the view is not changed. It could go further on coordinate system edge cases (e.g., empty drawing or extents of frozen layers), which is why it isn't a 5.

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

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

Three short labeled lines – purpose, side-effects, disambiguation – with the core action front-loaded and zero filler. Every sentence carries distinct information.

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

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

A parameterless read-only query with an output schema, so return-value documentation isn't required; the description nonetheless hints at the shape ([min_x, min_y, max_x, max_y]) and WCS frame, and covers side effects and view invariance. Nothing needed 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 zero parameters, so the baseline is 4; the schema is fully closed (additionalProperties: false) and there is nothing for the description to disambiguate. It correctly adds no noise about arguments.

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 (measure) and a precise resource (current drawing-space WCS extents), plus the mechanism (backend geometry engine). The disambiguation line distinguishes it from view-changing siblings such as view_zoom_extents, so an agent can select it without opening schemas.

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

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

Explicitly says it 'does not change view', which implicitly routes view-modifying needs to view_zoom_extents, and notes it does not alter document objects. It stops short of naming an alternative tool outright, so not a full 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 supply only readOnlyHint=false; the description adds the consequential details — that this mutates document state and deletes unreferenced layers, blocks, and styles. It does not say whether the purge is reversible via undo or whether it should be wrapped in a transaction, which are the remaining gaps given siblings like transaction_begin/undo exist.

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

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

Front-loaded with the action and gated with a warning before the labeled side-effect and disambiguation lines. There is mild redundancy — 'unused' appears in the opening line, the side-effects line, and the disambiguation line — but no sentence is wasted.

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

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

An output schema exists, so return values need no explanation, and with zero parameters the schema burden is nil. The description covers mutation, scope, and side-effects; only the reversibility/undo story is left unstated for a destructive document-wide operation.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly implies the operation is scoped entirely by document state rather than arguments.

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 ('Purge unused drawing resources from the active document') plus the exact target set (layers, blocks, styles). It is distinguishable from neighbors like drawing_audit or object_delete by its 'unused/referenced' scope, though it never names a sibling outright.

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

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

Gives a positive trigger ('clean up drawing before export') and an explicit exclusion ('only when removal is intended'), which is meaningful for an irreversible-feeling operation. No named alternative is offered, so it falls 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 only declare readOnlyHint=false, so the description carries most of the burden and does so: it discloses the side-effect ('Adds ARC entity to active space') and that the call returns a new drawing object. It still omits whether this is undoable or requires a transaction, but the mutation effect is clearly 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?

The core verb/resource sentence is front-loaded, and the side-effect and disambiguation lines are labeled so an agent can scan them in order. No sentence is filler.

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

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

With a full output schema and complete parameter docs, the main remaining gap for a creation tool is transactional scope, which is not addressed. The side-effect and alternative-tool notes cover the essentials an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so all seven parameters including layer and color defaults are already documented. The description restates the degree units and positive-radius constraint, which duplicates the schema rather than adding new meaning, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource ('Create an ARC at a WCS center') and pins down the defining parameters (positive radius, start/end angles in degrees). It explicitly names the sibling it is not, so an agent can separate it from entity_create_circle without opening either schema.

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

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

The disambiguation line states the selection rule: use this for circular arcs in degrees, use entity_create_circle for full circles. That is a concrete alternative with a condition, though there is no guidance on related cases such as polylines or ellipse-like 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?

The annotations only declare readOnlyHint=false, so the description usefully adds that the tool creates an entity in active space and returns the new object identifier. It does not discuss transaction requirements or permission constraints, but the side-effect is clearly disclosed.

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 short and front-loaded: core creation behavior first, then side-effects, then a clear disambiguation note. No sentence is wasted.

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

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

An output schema exists, the input schema is fully documented, and the description covers the mutation side-effect and return identifier. For a create-entity tool, this is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already explains cx, cy, radius, layer, and color. The description repeats key constraints such as WCS units and positive radius but adds no significant parameter meaning beyond 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 uses a specific verb and resource: create a CIRCLE at a WCS center with positive radius. It also distinguishes this tool from the sibling entity_create_arc by scope.

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 explicitly says when to use this tool (full 360-degree circles) and when to use the alternative (circular segments should use entity_create_arc). This is clear routing guidance.

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

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

Annotations only declare readOnlyHint=false; the description goes further by disclosing concrete side-effects (mutates active drawing state, advances document fingerprint) and the return value shape. It stops short of saying whether the call participates in a transaction or is undoable, which matters given transaction_begin/commit siblings.

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 lines, front-loaded with the core action, followed by side-effects and disambiguation. Nothing redundant; each sentence carries a distinct fact.

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

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

An output schema exists so return values need no explanation, and the description covers creation semantics, side-effects, and sibling routing adequately for an 8-parameter write tool. The only real gap is interaction with the transaction/undo tools, which is not addressed.

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

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

Schema coverage is 100%, so every parameter including defaults and ByLayer/active-layer fallbacks is already documented. The description restates 'layer/color' and 'drawing units' without adding syntax or constraints beyond the schema, so baseline 3 applies.

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

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

Names a specific verb and resource (create a LINE), pins the coordinate system (WCS endpoints in drawing units), lists optional attributes, and states the return value. It is immediately distinguishable from entity_create_polyline and the other entity_create_* siblings.

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 disambiguation line explicitly routes the agent: linear segments here, joined multi-segment paths to entity_create_polyline. That is an explicit alternative with the condition that selects it, not just implied context.

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

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

With readOnlyHint=false the mutation nature is already declared, and the description correctly reinforces this by disclosing the side-effect (adds LWPOLYLINE to active space) and that an identifier is returned. It says nothing about whether a transaction must be open first, whether the call is undoable, or what happens if the layer name does not exist — meaningful gaps for a write tool in a toolset that has explicit transaction_begin/commit siblings.

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 lines, each earning its place: capability and return value first, then side-effects, then disambiguation. No redundancy or filler.

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

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

An output schema exists so return-value detail is unnecessary, and annotations cover the safety profile. The description is nearly complete, but the omission of transaction/prerequisite behavior leaves a small gap for a mutating entity-creation tool that sits alongside explicit transaction controls.

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

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

Schema description coverage is 100%, so all seven parameters (points, closed, layer, color, bulges, widths, elevation) are already documented with defaults. The description only echoes the closed/layered/colored subset and the WCS drawing-units convention, adding little beyond the schema; the baseline of 3 is appropriate.

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

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

The description names a specific verb (Create) and resource (2D lightweight polyline) and constrains the input to WCS XY points in drawing units, plus the optional closed/layered/colored modifiers and the returned object identifier. It distinguishes itself implicitly from single-segment siblings like entity_create_line via the 'continuous multi-segment paths' phrasing, but never names the alternative explicitly.

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

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

The Disambiguation line gives clear when-to-use guidance: continuous multi-segment paths, contours, closed boundaries. It stops short of stating when NOT to use it or naming the specific sibling (entity_create_line, entity_create_arc) an agent should pick for simpler 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 declare readOnlyHint=false, so the description must add the mutation profile — and it does: 'Side-effects: Adds TEXT entity to active space' tells the agent which space is modified and that state changes. 'Return its identifier' also sets expectations for follow-up calls. Missing are failure modes (non-existent layer, no open document) and whether the entity is undoable.

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

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

Three short sentences, front-loaded with the action and geometry, then side-effects, then disambiguation. No filler and no repetition of schema defaults.

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

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

With an output schema present, return values need no explanation, and the description covers the mutation side-effect and intended use cases. The remaining gap is preconditions — whether a document must be open and whether the target layer must already exist — which matters for a 7-parameter creation tool.

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

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

Schema description coverage is 100% and every parameter is documented with units and defaults, so the schema does the heavy lifting. The description's mention of height in drawing units, rotation in degrees, and optional layer/color only restates what the schema already says, matching the baseline 3.

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

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

The first sentence gives a specific verb (Create) and resource (TEXT entity) plus the exact geometric semantics: WCS insertion point, drawing-unit height, rotation in degrees. The Disambiguation line separates it from the sibling entity_create_* primitives and from annotation tools like dimension_linear, so an agent can route 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?

'Use for labels, callouts, and notes' gives clear positive usage context, and 'optionally on a layer/color' implies baseline defaults. It stops short of explicit exclusions (e.g., use dimension_linear for measurements, batch_create_entities for bulk text), so it's strong but not fully routing.

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

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

With only readOnlyHint=false, the description does add real value: it discloses atomic mutation of active drawing state, full rollback on failure, and optimistic locking via the expected predecessor fingerprint. Beyond that it omits what a rollback means for already-created entities, permission/auth needs, and how idempotency via correlation_id actually behaves on retry, so the disclosure is partial.

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

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

Front-loaded with the core action and clearly segmented into Side-effects and Disambiguation labels, with no filler sentences. Slight deduction for vague jargon such as 'generic feature' and 'micro-chunk' that is never unpacked.

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

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

Covers the transactional contract (atomicity, rollback, optimistic locking) for a 6-required-parameter mutation tool, and an output schema exists so return values need no explanation. It stops short of describing what action types the actions array accepts or how correlation_id idempotency resolves conflicts.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters, making 3 the baseline. The description reinforces the coupling of document_pid and expected_parent_fp as a version-bound transaction but adds no new format, constraint, or failure semantics beyond what the schema fields state.

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 ('Execute') and resource ('one complete generic feature'), plus the transactional scope bounded to document PID and predecessor fingerprint. It implicitly differentiates from the batch_* siblings by calling itself the 'preferred route for multi-step feature creation', but it never names those siblings, so the differentiation is inferential rather than explicit.

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

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

'Preferred route for multi-step feature creation' gives a clear positive condition for selecting this tool over the single-step entity/block tools. However, no exclusion or counter-case is given (e.g., when to use batch_create_entities or transaction_begin instead), so an agent must infer the boundary.

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 readOnlyHint=false, so the description carries most of the burden and does: it discloses the side-effect ('Adds HATCH entity to active space') and the failure mode (invalid or unsupported boundaries are refused), which the agent cannot infer from structured fields. It doesn't mention transactions/undo or what error surface the refusal produces.

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

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

Three short sentences, front-loaded with the action, then explicitly labeled 'Side-effects' and 'Disambiguation' blocks. No filler or restatement of the name.

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

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

For a single-entity creation tool with a full output schema and fully documented parameters, the description covers what matters: geometry precondition, side-effect, and refusal behavior. Only the transactional/error-recovery context 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 100% and each parameter is individually documented with defaults, so the description's mention of pattern/scale/angle adds little beyond orientation. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Create a hatch') plus the key inputs (pattern, scale, angle) and the coordinate context (closed WCS XY boundary). The Disambiguation line ('Use to fill closed contours') separates it from the entity_create_* family, though no hatch-specific sibling exists to contrast against.

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

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

Explicitly states the applicability condition ('use to fill closed contours') and the precondition ('boundary must be closed and coplanar'), plus that invalid/unsupported boundaries are refused. It stops short of naming an alternative tool for open or non-coplanar geometry, but the selection context is clear.

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

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

"Side-effects: None. Read-only guidance query" restates what readOnlyHint=true already declares, so it earns no extra credit. Beyond that it discloses the nature of the returned content (including refusal notes, which hints at what an agent may find when a request is disallowed), which is modest added value. With annotations and an output schema covering the rest, 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?

Three short labeled lines – purpose, side-effects, disambiguation – each earning its place, with the core purpose front-loaded in the first sentence. No filler or redundancy.

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

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

With an output schema present, the description need not explain return values, and zero params plus readOnlyHint mean little else is required. A minor gap remains: it doesn't say whether the guidance is static boilerplate or reflects current server state, which would affect how often an agent should 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?

The tool takes zero parameters, so per the baseline rule this scores 4. There is nothing parameter-related the description could usefully add.

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 ("Return") and enumerates the concrete payloads: provider contract guidance, workflow rules, capability map, refusal notes. The final line explicitly distinguishes it from sibling system_capabilities, so an agent can separate the two without opening either schema.

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

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

The disambiguation line gives an explicit when-to-use rule and names the alternative tool with the condition that selects it (machine-readable JSON flags). Nothing is left to inference about routing between help and system_capabilities.

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 readOnlyHint=false, while the description adds important behavior: it mutates the drawing by adding a layer table record, refuses duplicates, and leaves the active layer unchanged. These are exactly the side-effect and failure-mode details an agent needs before calling a write tool.

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

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

Front-loads the core action, then separately states side-effects and disambiguation in short, scannable sentences. There is no wasted wording.

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 full schema coverage, an output schema, and relevant annotations, the description covers the missing behavioral context: what it creates, what it refuses, what it does not change, and which sibling to use for updates.

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

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

Schema description coverage is 100%, and the schema already documents both parameters, including the ACI range/default and name uniqueness. The description reinforces the color-index and uniqueness semantics but does not add substantial parameter detail beyond the schema.

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

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

States a specific verb and resource ('Create a new layer') plus key scope details: AutoCAD color index, duplicate-name refusal, and no change to the active layer. This clearly distinguishes it from layer_update_state and layer_set_current.

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 says existing names are refused and directs the agent to layer_update_state for modifying existing layers. The note that the active layer is not changed also clarifies that this tool is not for making a layer current.

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 the description's 'Side-effects: None. Read-only layer query.' largely restates that. It does add the returned field set, which is modestly useful, but nothing about ordering, inclusion of xref-dependent layers, or empty-drawing behavior is disclosed.

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 labeled lines, purpose first, then side-effects, then usage. Every sentence carries distinct information 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?

For a zero-parameter read-only list with an output schema, the description covers purpose, safety, and usage. Only a naming of the alternative layer tools would make it fully self-sufficient for routing.

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

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

The tool takes no parameters, so there is no parameter semantics to explain; the baseline for a zero-parameter schema applies. Nothing in the description misleads about 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 ('List') and resource ('drawing layers') and enumerates the returned attributes (names, colors, linetypes, visibility/frozen/locked, current flag), which distinguishes it from layer_create, layer_set_current, and layer_update_state by making clear it is the read path.

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 disambiguation line gives an explicit situation: 'Use to inspect existing layers before placing entities.' That is a clear use context, but it names no alternative tool and offers no exclusion (e.g., when to prefer object_query or layer state tools instead).

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

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

With only readOnlyHint=false available, the description carries real weight: it discloses the side-effect (changes the working layer for subsequent entity creation), clarifies that existing objects are not re-assigned, and labels it as session drawing state. It stops short of saying whether the setting persists on save or is undoable, which would be the remaining behavioral detail.

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, labeled sentences, front-loaded with the core action, then side-effects, then disambiguation. No sentence is redundant or restates the tool name.

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?

One required parameter, an output schema, and a minimal annotation set — the description supplies exactly the missing pieces (state change scope, non-mutation of geometry) without needing to explain return values. Nothing an agent needs to invoke it correctly is absent.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema, so the baseline applies. The description reinforces the 'existing layer' constraint (implying an error if the name is unknown) but adds no format or resolution details beyond the schema.

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

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

States a specific verb and resource ('Set an existing layer as the active document layer') and immediately scopes it ('existing layer', not creation). An agent can distinguish it from layer_create and layer_update_state 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?

The Disambiguation section makes explicit what the tool does not do (does not modify existing entities, only sets active context), which prevents misuse after a layer rename or property change. It does not name sibling tools such as layer_create or layer_update_state as alternatives, so routing is inferred rather than stated.

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

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

Annotations only declare readOnlyHint=false, so the description carries most of the burden and does it well: it discloses the side-effect (modifies layer table properties), the allowlist constraint, and that unsafe changes to the current layer are refused before mutation. It stops short of stating permissions or reversibility/undo 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?

Three short, labeled lines with the core action front-loaded followed by side-effects and disambiguation. No redundancy; every line contributes distinct information.

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

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

With an output schema present, return values needn't be explained, and annotations are minimal but the description covers safety and side-effects. A minor gap remains around what happens on partial failure or whether changes are undoable, but overall it is complete enough to call correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented with type and example (e.g. ACI 1-255, lineweight in 1/100 mm). The description's field list adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Update allowlisted layer state') and enumerates the mutable properties (on/off, frozen, locked, color, linetype, lineweight). This clearly distinguishes it from layer_create, layer_set_current, and object_set_properties.

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 disambiguation line explicitly says when to use it: to change layer visibility or styling across all entities on that layer. It lacks an explicit 'when not to use' or a named alternative (e.g. layer_set_current for switching the active layer), so it falls 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 only declare readOnlyHint=false, so the description carries real weight: it discloses the side effect ('Adds layout to drawing'), the failure mode for duplicate/empty names, and the guarantee that existing layouts are preserved. It doesn't state what is returned or whether the new layout becomes current.

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 labeled lines, zero filler, and the core creation statement plus name constraint are front-loaded before the side-effect and disambiguation notes.

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

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

With an output schema present and only one parameter, the description covers purpose, side effect, refusal behavior, and next step. The one notable omission for an agent is whether the newly created layout becomes the current layout, given the existence of layout_set_current.

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

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

Schema coverage is 100% with a single documented parameter, so the baseline is 3; the description adds meaningful constraint semantics ('duplicate or empty names are refused') that the schema does not express, which justifies the bump.

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 plus resource ('Create a new paper-space layout by name') and explicitly contrasts the tool with viewport_create, so the agent can distinguish it from siblings without opening any schema.

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

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

It names the alternative explicitly ('viewports must be added separately with viewport_create') and states the when-not condition (duplicate or empty names are refused). It doesn't discuss how this relates to layout_set_current or when a caller would pick an existing layout instead, so it falls short of full 5-level guidance.

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

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

The annotations already declare readOnlyHint=true, and the description reinforces this with 'read-only' and 'Side-effects: None.' It adds a small amount of context by noting that it does not change active model/paper space, but it largely repeats the annotation and does not add other behavioral details.

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 short and front-loads the core purpose. 'Side-effects: None. Read-only layout query.' is somewhat redundant with the first sentence, but the disambiguation line adds useful structure without excessive length.

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 list operation with no parameters, an output schema, and explicit read-only annotations, the description gives enough context for an agent to call it correctly. Return values are covered by the output schema, so no additional detail is required.

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. With an empty input schema and 100% schema description coverage, the baseline score of 4 is appropriate.

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

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

The description states a specific verb and resource: 'List document layouts and identify the current layout.' It distinguishes itself from mutation siblings by emphasizing read-only behavior and by saying it is for discovering printable sheets, though it does not explicitly name alternatives like layout_create or layout_set_current.

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 line 'Use to discover printable sheets' gives a clear usage context, and the read-only/no-change framing implicitly separates it from layout modification tools. However, it does not explicitly state when not to use it or name the sibling alternative for changing layouts.

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 state readOnlyHint=false, indicating a mutation. The description adds meaningful context by disclosing the side-effect: changing the operator's active space context. It does not cover failure behavior for invalid layout names, but the key behavioral impact is disclosed.

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 appropriately sized and front-loads the action. However, it repeats the same idea twice: 'changes the operator's current model/paper-space context' and 'Changes operator active space context.' That redundancy slightly weakens efficiency.

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 mutation annotation, single required parameter, output schema, and clear side-effect disclosure, the description is nearly complete for an agent to call it correctly. Only minor gaps remain, such as failure handling when the named layout does not exist.

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

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

Schema description coverage is 100%, with the single 'name' parameter already documented and exemplified in the schema. The description adds no additional parameter meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb and resource: switching the active document to an existing layout. It clearly distinguishes this from creating layouts by saying 'existing layout' and clarifies the model/paper-space context. It stops short of naming sibling tools like layout_list or layout_create, so a 4 rather than a 5.

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

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

The phrase 'Switch between Model and paper layouts' implies when to use the tool, and 'existing layout' implicitly excludes creation. However, it does not explicitly state when not to use it or name layout_list/layout_create as alternatives, leaving usage guidance to inference.

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

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

"Side-effects: None. Read-only metadata query" simply restates the readOnlyHint annotation that the agent already has, so it adds no behavioral context. Nothing is said about behavior for an unknown namespace, whether a namespace must be written first via metadata_set, or any native-bridge failure modes.

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

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

Front-loads the purpose in one sentence and keeps the rest short. The side-effects sentence is largely redundant with the annotation, a small amount of wasted space.

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

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

Annotations carry the safety profile, the schema fully documents both params, and an output schema exists, so return values need not be described. What is missing is only edge-case behavior (missing namespace, namespace scope per PID), which is modest given the supporting structure.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema; baseline 3 applies. The description echoes the "schema-agnostic namespace" and "persistent semantic PID" wording but contributes no extra format or constraint detail.

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

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

States a specific verb and resource: reading one metadata namespace for a persistent semantic PID. The disambiguation line hints at the difference from metadata_query/metadata_set, but never names those siblings, so the agent must infer the boundary.

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

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

"Use to retrieve engineering attributes attached to entities" implies when to reach for it, but there is no explicit when-not condition and the obvious alternatives (metadata_query, metadata_set) are not named. Usage is inferable rather than stated.

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

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

The readOnlyHint annotation already declares the safety profile, and the description mostly restates it ("Side-effects: None. Read-only metadata query."), which earns no additional credit. It does add scope context ("bounded", "across the active native document") but says nothing about behavior on no matches, on an unknown namespace, or on type mismatches in equals — with annotations carrying safety, 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?

Three labelled, front-loaded sentences that are easy to scan, with the core purpose first. The middle sentence is largely redundant with the readOnlyHint annotation, which is the only real waste.

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

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

With an output schema present and full parameter coverage, the description need not explain returns or pagination, and it supplies purpose, scope and disambiguation. The remaining gap is conceptual — what a "schema-agnostic metadata namespace" actually contains and what an empty match set means — which is a modest but real shortfall for a niche tool.

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

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

Schema description coverage is 100%, so path, equals, namespace, limit and offset are already documented in the schema. The description only echoes path and equals semantics and adds nothing about what a namespace key looks like or whether matching is exact/case-sensitive beyond the word "exact". Baseline 3 is correct.

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 (query) and resource (a metadata namespace on the active document) with the matching condition spelled out (one dotted JSON path to an exact JSON value). It is clearly not a write tool, but it never names its closest siblings metadata_get / metadata_set, so the agent must infer the boundary between querying, reading, and writing metadata.

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 Disambiguation line gives a concrete selection rule: use this to locate entities by engineering metadata rather than visual layers, which implicitly contrasts with object_query/layer-based tools. It stops short of explicit when-not conditions or naming the metadata_get/metadata_set alternatives for single-key versus multi-entity access.

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

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

Goes well beyond readOnlyHint=false by declaring the side-effect (attaches XData/extension dictionary metadata to the entity) and the optimistic-locking guard on the predecessor fingerprint. It still does not say what happens on a fingerprint mismatch (error vs. silent no-op) or whether an existing namespace is overwritten, so the mutation semantics remain partially opaque.

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 labeled statements, each carrying distinct information (precondition, side-effect, disambiguation), with the operation and its guard front-loaded. No sentence is redundant.

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

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

For a five-required-parameter mutation tool with an output schema and minimal annotations, the description covers the precondition, the write's side-effect and the intended use. Missing are failure behavior on a stale fingerprint and the overwrite/replace semantics of an existing namespace, which an agent would want before calling.

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

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

Schema coverage is 100%, so every parameter is documented in the schema, including the optimistic-locking role of expected_parent_fp. The description only reinforces the fingerprint-match precondition already stated in the schema and adds no format or constraint detail for namespace or value, so the baseline of 3 applies.

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

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

States a specific verb and resource: set one bounded schema-agnostic JSON metadata namespace on an entity, and labels it as a write operation. It is easily distinguished from metadata_get and metadata_query by the write verb, though it does not name those siblings explicitly.

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

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

The Disambiguation line gives a concrete use case (store engineering properties such as part numbers and materials on entities), and the first sentence gives the calling precondition (document PID and predecessor fingerprint must still match). It never names an alternative tool or a when-not-to-use condition, which keeps it 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 provide only readOnlyHint=false, so the description carries the load and does so: it declares the persistent dictionary write, the fingerprint advance, and a hard refusal condition on non-empty drawings. That is exactly the mutation/blast-radius context an agent needs before calling a write tool.

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

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

Three sentences, each doing distinct work: the action, the side effects, and the disambiguation/precondition. No repetition and no filler.

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

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

Output schema exists, so return values need no explanation, and the description still covers side effects and refusal behavior. It does not address re-entrancy (what happens if invoked twice on an already-initialized drawing beyond the refusal) or whether the write can be undone, which would round it out.

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 schema is trivially complete and the description has nothing to add on inputs. Per the zero-param baseline this would be a 4, but the description mentions return values ('verified document PID and semantic fingerprint') rather than any parameter meaning, offering no input-side value.

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

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

Names a specific verb ('initialize') and resource ('provider-owned persistent document lineage') and states the return ('document PID and semantic fingerprint'). The heavy jargon ('semantic fingerprint', 'native tracking') slightly obscures the plain intent, but an agent can still distinguish it from native_integrity_status, which reads status rather than bootstrapping it.

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

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

Explicitly conditions use: 'Use once on an empty drawing to bootstrap native tracking; refuses non-empty drawings' — giving both the when and the when-not. It stops short of naming an alternative tool to consult first, which keeps it from 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 the description reinforces the read-only, no-side-effects behavior. It adds useful context about what is being verified (bridge liveness, optimistic lock state, persistent document PID, semantic fingerprint), though it does not elaborate on failure modes or result semantics beyond the output schema.

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

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

The description is short, front-loaded with the core purpose, and then adds side-effect and disambiguation notes. Every sentence carries useful routing or safety 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?

Given the zero-parameter schema, existing output schema, and readOnlyHint annotation, the description supplies enough context to identify the tool, understand its safety profile, and route between it and system_status. No essential invocation detail 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 zero parameters, so parameter semantics are not a meaningful differentiator. The baseline for a zero-parameter tool is 4, and nothing in the description needs to compensate for missing parameter documentation.

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 inspect action over a clearly named resource: the same-session managed native bridge and active AutoCAD document binding, including PID and semantic fingerprint. It is readily distinguishable from sibling tools, especially system_status, which is named in the disambiguation.

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 says to use this tool to verify native C# bridge liveness and optimistic lock state, and directs overall provider status checks to system_status. This gives a concrete use case and an alternative rather than leaving routing to inference.

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

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

The annotations only state readOnlyHint=false, so the description carries most of the behavioral explanation. It discloses the key side effect — creates a duplicate entity at the offset location — and clarifies that the source is not deleted. It does not discuss permissions or undo/transaction behavior, but the core mutation semantics are clear.

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 front-loaded with the main action and return behavior, followed by brief side-effect and disambiguation notes. Every sentence adds useful information 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?

The tool has an output schema, so the description need not explain return structure. It still notes that the new entity identifier is returned, and it covers the essential mutation and disambiguation details for correct invocation.

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

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

Schema description coverage is 100%, so dx, dy, dz, and object_id are already documented in the input schema. The description reiterates WCS delta and drawing units but does not add syntax or constraints beyond the schema, making the baseline 3 appropriate.

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

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

The description uses a specific verb and resource: copy one object via WCS delta dx/dy/dz. It also states the return value and that the source is not deleted, and it distinguishes the operation from object_move.

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 explicitly names the alternative behavior: use object_move to translate without duplication. This gives the agent a clear rule for choosing between copying and moving.

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 safety profile is known; the description reinforces it with 'no document geometry is modified' and adds the useful scoping detail that counting is limited to the backend's current supported space. Slight redundancy with the annotation, but it adds the space constraint.

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

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

Front-loaded with purpose, then labeled sections for side-effects and disambiguation. There is mild repetition between 'no document geometry is modified', 'Side-effects: None', and 'Read-only', which costs a bit but the rest earns its place.

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

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

With an output schema, annotations, and fully described parameters, the description covers what an agent needs to call this correctly. The only soft spot is that 'current supported space' is not defined, but the tool is simple enough that this is minor.

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?

Both parameters are already fully documented in the schema (100% coverage, with type examples like 'LINE', 'CIRCLE'). The description only mentions that type and layer filters exist, which the schema already conveys, so baseline 3 applies.

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

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

States a specific verb and resource ('count objects') plus the scope ('backend's current supported space') and the filterable dimensions. An agent can distinguish it from object_list/object_query 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?

The disambiguation line gives a clear usage pattern: run a lightweight count first, then fetch full object lists if needed. It doesn't explicitly name object_list/object_query as the alternatives, but the intended workflow is unambiguous.

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 readOnlyHint=false, so the description carries most of the load and does so well: it states the deletion is destructive and permanent in effect, names the side effect on the active drawing, and warns about timeout/idempotency ambiguity on retry. It stops short of saying whether undo can restore the deleted entity, or how it behaves for locked layers or entities referenced by blocks — relevant gaps for a destructive tool.

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

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

Front-loaded with the action and target, then segmented into labeled Side-effects and Disambiguation clauses — easy to scan. Minor redundancy: destruction is stated three times (main sentence, side-effects line, disambiguation line), one of which could be cut.

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

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

An output schema exists so return values need no explanation, and the description covers the critical behaviors for a destructive one-param tool: what is destroyed, scope, and retry hazard. It leaves out failure modes (unknown/stale object_id), and whether the deletion is undoable via the undo sibling, which would round it out for the agent.

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

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

Schema coverage is 100% and the single parameter is documented there, so the baseline is 3. The description adds value by narrowing scope to the active document and identifying the identifier as a backend object identifier, which constrains what a valid value can be.

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 (delete), a precise scope (one object), the identifier type (backend object identifier), and the document context (active document). This distinguishes it clearly from object_list, object_get, object_query, and object_set_properties without needing 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?

Explicitly names the alternative and the condition that selects it: use object_set_properties(visible=False) when temporary hiding is preferred. It also flags a retry precondition (reconcile timeout uncertainty before retry), which is exactly the kind of when-to-use guidance an agent needs for a destructive operation.

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 restates readOnlyHint=true with 'Side-effects: None. Read-only entity query.', which is duplicative of structured data rather than additive. It does not cover failure behavior (e.g., what happens with an unknown or stale handle) or permission requirements. With annotations covering the safety profile and an output schema present, 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?

Four short lines, front-loaded with the core action and return payload, then side-effects, then routing. No sentence is filler and structure is 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?

For a single-parameter read tool with annotations and an output schema, the description covers purpose, safety, and routing. The only gap is failing to differentiate from object_list/object_query, which matters given the dense object_* sibling group.

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

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

Schema coverage is 100% and the sole parameter's description ('Backend entity identifier or persistent CAD handle') matches the description's phrasing, so the description adds no meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Read one object by backend object identifier') and enumerates exactly what is returned (type, layer, color, visibility, geometry, space metadata). This lets an agent distinguish it from the write-side object tools 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 Disambiguation line gives an explicit condition and alternative: single entity inspection here, calculated metrics via object_measure. However, it omits the more immediate lookalikes in the sibling set — object_list and object_query — leaving the agent to infer why it should pick object_get over those.

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 readOnlyHint, and the description does add real behavioral content beyond them: the fail-closed failure semantics ('unsupported solvers fail closed rather than approximate silently'), which an agent cannot infer from structured data. The 'Side-effects: None / Read-only' lines merely restate the annotation, keeping it from a 5.

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

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

The core behavior and the failure-semantics caveat are front-loaded in the first sentence. Two of the follow-on lines are partly redundant — 'Side-effects: None' and 'Read-only intersection solver' duplicate the readOnlyHint annotation and each other — but the description stays short.

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 (no need to describe return values), full schema coverage, and readOnlyHint annotations, the description supplies exactly the missing piece: that unsupported cases error out rather than silently approximating. An agent can call this correctly without further information.

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

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

Schema description coverage is 100%, so the schema already documents first_id, second_id, and the extend_mode values. The description echoes the explicit extension mode but adds no format, ordering, or constraint detail (e.g., what happens when the two ids are identical or of incompatible types), so baseline 3 applies.

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

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

States a specific verb and resource ('Compute exact supported intersections between two distinct objects') and names the governing knob (extension mode). It is distinguishable from measurement/mutation siblings, though 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 'Disambiguation' line gestures at usage ('computes geometric intersection points with extend options') and the phrase 'two distinct objects' implies a precondition, but there is no explicit when-to-use vs when-not, and no naming of an alternative approach (e.g., object_measure) for non-intersection queries.

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 readOnlyHint=true, so 'Side-effects: None. Read-only entity query.' largely restates structured data, but the description adds real value beyond that: results are bounded by pagination and the returned IDs are backend identifiers rather than drawing handles. That ID-semantics note is context an agent cannot get from annotations or the schema.

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

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

Front-loaded with purpose, then three short labeled clauses; nothing is buried. The 'Side-effects: None' line is slightly redundant with the annotation, but it is compact and does not distract.

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. Scope, safety, pagination bounding, ID semantics, and sibling routing are all covered. Minor gap: no indication of result ordering or that zero filters returns the entire space, which matters for a default-200-paginated listing tool.

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

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

Schema description coverage is 100%, with limit/offset defaults and example entity types already documented per-property. The description only gestures at 'type/layer filters and bounded pagination' without adding format or interaction detail (e.g. whether filters combine, what bound applies). Baseline 3 is appropriate.

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

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

States a specific verb and resource ('List objects from the backend's current supported space') plus the filter and pagination scope, and explicitly names the sibling it is not (object_query). An agent can distinguish it from object_get, object_count, and object_query 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 an explicit positive selection rule ('use for sequential browsing') and the exact condition that should route the agent elsewhere ('use object_query when spatial filtering or bounding box measurements are needed'). Alternatives and exclusions are both 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?

The annotations already declare readOnlyHint=true, and the description reinforces this with 'Side-effects: None' and 'Read-only measurement query.' It adds useful behavioral context by stating that results are deterministic and type-specific, though it does not describe backend support limitations or failure conditions.

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 short, front-loaded, and structured into purpose, side effects, and disambiguation. Every line contributes to selecting or safely invoking the tool.

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

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

For a read-only, single-parameter tool with an output schema and readOnlyHint annotation, the description is largely complete. The main remaining gap is sibling routing: it does not explicitly distinguish measurement from object inspection or extents queries.

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

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

Schema description coverage is 100%, so the single object_id parameter is already fully documented in the schema. The description does not add further meaning about accepted identifiers, resolution behavior, or lookup semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: measure one object. It also defines the output scope as type-specific metrics plus a WCS bounding box, which is clearer than a generic object inspection tool. However, it does not explicitly name sibling alternatives such as object_get, solid_inspect, or drawing_extents.

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

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

The phrase 'Read-only measurement query' implies the use case, and 'Disambiguation' suggests it is for deterministic mathematical metrics. But there is no explicit guidance on when to choose this tool versus object_get, solid_inspect, drawing_extents, or object_intersections.

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