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

The readOnlyHint annotation already declares the safety profile, and the description's 'Get' is consistent with it. The description adds scoping context ('all entities') and clarifies the return concept ('extents'), but it does not address edge cases like empty drawings or coordinate system behavior. With annotations covering the primary behavioral trait, this is adequate but not rich.

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

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

The description is a single front-loaded sentence with no filler. Every word adds meaning and the parenthetical clarification 'extents' improves precision without bloating the text.

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

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

For a parameterless read-only tool with an output schema present, the description provides all information an agent needs to select and invoke it. There are no hidden inputs, prerequisites, or behavioral warnings 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 has zero parameters and the input schema is empty, so there are no parameter semantics to document. The baseline for zero-parameter tools 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 uses a specific verb ('Get') and a specific resource ('bounding box (extents) of all entities in the drawing'). The 'all entities' scope distinguishes it from selection-based and measurement-based analysis 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 description implies usage when overall drawing extents are needed, but it does not explicitly state when to use this tool versus alternatives like analysis_measure_entity or view_zoom_extents. No exclusions or alternative-routing guidance are provided.

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

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

Annotations already mark readOnlyHint=true, so the read-only safety profile is covered. The description adds useful behavioral context beyond that: the tool returns total_entities, by_type, and by_layer with sorted ordering, which helps set expectations for the response shape.

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 action, and clearly structured. The 'unique to AutoCAD MCP Pro' claim is extraneous and does not help an agent invoke the tool, but it does not obscure the operational content.

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

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

For a zero-parameter, read-only analysis tool with an output schema, the description is complete. It names the output fields, explains the grouping and sorting, and is adequately scoped to the active drawing.

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 the schema is fully covered by definition. The description usefully documents the return object fields, which is the only input-free semantics 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?

The description states a concrete action and output: analyzing the drawing and returning entity counts grouped by type and layer, sorted by count. It is clear enough to distinguish from drawing creation or modification tools, though it does not explicitly differentiate from the closely related analysis_layer_stats sibling.

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

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

No guidance is provided on when to use this tool versus analysis_layer_stats, analysis_select_by_type, or drawing_info. The uniqueness claim is about market positioning, not about usage context or alternatives.

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 mark readOnlyHint=true, but the description adds important behavioral context beyond that: it warns that queries are uncapped and can return every hit in a busy drawing, with a performance-oriented mitigation. This helps the agent anticipate large results and plan output handling.

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

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

The description is compact, front-loaded with the core purpose, and every sentence adds value. The uncapped warning and the fields/compact advice are directly actionable without any 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?

Given the output schema exists, annotations cover the read-only nature, and the input schema fully documents parameters, the description is complete. It even covers the most important operational caveat—uncapped result size—which is exactly the kind of context an agent needs before invoking the 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%, and the schema already explains all six parameters, including field projection syntax, unknown-name behavior, and the compact envelope. The description reinforces a useful strategy for fields/compact but does not add new parameter-level meaning 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 action ('Find all entities'), a specific resource ('within a rectangular region'), and even clarifies the selection mode ('crossing selection'). This clearly distinguishes it from broader listing tools like entity_list and selection-based siblings without needing to inspect 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 description gives clear practical guidance: results are uncapped, so users should project with fields and/or compact before widening the window. It does not explicitly name sibling alternatives, but the context around when and how to invoke it safely is clear and actionable.

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, so the safe read behavior is established. The description adds modest context by clarifying that it reports per-layer aggregate counts and types, which goes slightly beyond the annotation. No contradiction is present.

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

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

A single, front-loaded sentence with no filler. Every element — 'each layer', 'entity count', and 'types present' — adds meaningful information.

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

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

For a parameterless, read-only tool with an output schema, the description is sufficiently complete. It states the scope and the kind of statistics returned, and no parameter or 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 has zero parameters and schema description coverage is 100%, so there are no parameter semantics for the description to clarify. The baseline of 4 applies for a parameterless tool.

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

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

The description uses a specific verb ('Return') plus a clear resource ('detailed statistics for each layer') and names the actual content (entity count, types present). It is distinguishable from siblings by the layer-level scope, though it does not explicitly differentiate from analysis_entity_stats or analysis_list_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?

No guidance is given about when to choose this tool over siblings such as analysis_entity_stats or analysis_list_properties. The intended usage is implied by the name and description, but no selection conditions or exclusions are stated.

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

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

Beyond the readOnlyHint annotation, it discloses that coordinates are WCS, extrusion is reported, and the payload is the raw attribute set entity_get omits. This lets an agent correctly interpret the coordinate frame without having to guess from 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 first sentence establishes the tool in a few words. The second sentence adds two useful behavioral facts, WCS and extrusion, plus the relationship to entity_get, so 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 only one required parameter, an output schema, and a read-only annotation, the description covers the important behavioral caveats. Nothing an agent needs to call 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 input schema already gives handle a full description, and schema coverage is 100%. The tool description adds no new meaning about handle beyond what the schema provides, so the high-coverage baseline 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: dump/returns the full DXF attribute set for one handle, framed as AutoCAD's LIST. It also distinguishes this from entity_get by noting entity_get deliberately does not carry dxf_attributes.

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 obvious alternative, entity_get, and gives the selection condition: use this when you need the raw attribute set that entity_get omits. It does not enumerate when not to use this, but the one clear sibling contrast is enough.

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

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

Beyond the readOnly and idempotent annotations, the description discloses that the tool measures the numbers in the call, not the drawing, and that results are exact only for straight-edged polygons. It also warns about under-reporting on curved edges when bulge is omitted and references an 'assumes' field, adding meaningful behavioral context.

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

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

Three tight paragraphs with no filler. The main purpose is front-loaded, and every sentence adds either capability, usage routing, accuracy caveats, or schema-related context. The formatting makes the key warnings 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 tool with a detailed input schema, an output schema, and safe read-only annotations, this description is complete. It covers what the tool does, when to use the alternative, how curved edges affect accuracy, and what assumptions the output reports.

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?

Although the schema already documents the points array well, the description adds important semantic nuance: it clarifies the tool operates on literal coordinates rather than drawing entities, explains the bulge element's role in arc edges, and quantifies the accuracy penalty of omitting it. This goes well beyond the baseline schema coverage.

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: it computes the area and perimeter of a polygon from supplied vertices. It also clearly differentiates itself from the sibling analysis_measure_entity, which measures real drawing geometry.

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

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

The description explicitly says when to use this tool versus the alternative: use it only when you have literal coordinate vertices, and use analysis_measure_entity(handle) to measure something that already exists in the drawing. This gives an agent unambiguous routing guidance.

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

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

The description is consistent with the readOnlyHint and idempotentHint annotations, and it adds meaningful behavioral detail by specifying 'Euclidean distance,' signaling a pure mathematical calculation rather than a geometric entity measurement. It does not mention units or drawing-plane assumptions, but the annotations already cover the safety and side-effect profile.

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

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

The description is a single, front-loaded sentence with no filler or redundant restatement of the tool name. Every word contributes to understanding what the tool does.

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

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

This is a simple two-point distance calculation with a full output schema and complete parameter descriptions, so the description is mostly sufficient. The only missing piece is explicit guidance on when to use this tool versus naming sibling measurement alternatives, but the low operational complexity keeps this from being a major gap.

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

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

Schema description coverage is 100%, with each of the four parameters already described as 'Point 1 X,' 'Point 2 X,' etc. The tool description adds no further meaning beyond the schema, so the 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?

The description states a specific verb ('Measure') and a precise object ('Euclidean distance between two points'), which clearly distinguishes it from sibling tools like analysis_measure_area or analysis_measure_entity. The mention of 'Euclidean' also defines the exact math operation rather than leaving it vague.

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 'between two points' implies the tool is appropriate when the user has two coordinate pairs and wants straight-line distance, but it does not explicitly compare against alternatives such as analysis_measure_entity or analysis_measure_area. There is no when-not-to-use guidance or exclusion of other measurement tools.

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

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

Annotations declare readOnlyHint and idempotentHint, and the description adds substantial behavioral context beyond that: it reads real geometry including polyline bulges, exposes accuracy flags (exact, assumed_closed, self_intersecting), and documents distinct error modes for unsupported entities. This is exactly the kind of disclosure that helps an agent predict side effects and failure behavior.

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

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

Every sentence earns its place: the purpose is front-loaded, the geometry-fidelity caveat is meaningful, the supported/unsupported type lists are compact, and the accuracy-flag explanation is essential. The description is longer than average but not wasteful — its length is justified by the tool's complexity.

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

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

Given an output schema and clear annotations, the description covers supported input types, capability-gated failures, plain errors, accuracy semantics, and the source of the handle parameter. Nothing an agent needs to call this tool correctly or interpret its results is left unexplained.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds useful context by explaining how flatten_tolerance relates to the reported accuracy flag and why bulge-aware measurement matters, reinforcing the parameter's purpose beyond the raw 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 — measure an entity by handle — and enumerates the exact geometry types it supports. The description clearly centers on area measurement while distinguishing it from generic listing/stat tools by its geometry-fidelity guarantees. An agent can tell what this tool does without ambiguity.

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

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

Provides strong applicability context: lists measurable entity types, explicitly calls out LINE/TEXT/INSERT as errors, and explains that REGION/3DSOLID require a COM capability. It stops short of naming sibling tools like analysis_measure_area or analysis_measure_distance and saying when to prefer them, but the when-to-use and when-not-to-use guidance is otherwise 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 readOnlyHint=true annotation, the description discloses a critical hidden behavior: the MAX_LIST_LIMIT cap at 5000 and the fact that the plain list cannot report truncation because the warning only goes to the log stream. It also explains that compact=True exposes the layer's real population via total and indicates truncation via truncated. This is exactly the behavioral context an agent needs.

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

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

The description is two short paragraphs with no filler. The first sentence states the operation and output; the second paragraph front-loads the cap and gives actionable guidance. Every sentence contributes necessary information.

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

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

For a read-only selection tool with an output schema and fully described parameters, the description covers purpose, return type, truncation edge case, and the corrective parameter for accurate counts. Nothing critical is missing for an agent 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?

With 100% schema description coverage, the baseline is already strong, and the compact parameter's schema description is detailed. The tool description adds further value by explaining why compact matters—it is the only shape that reports truncation—and clarifying that total represents the layer's true population. This goes beyond the schema without being redundant.

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 'Get all entities on a specific layer', a specific verb and resource, and clarifies the return type with 'Returns entity list with handles'. The layer scope distinguishes it from sibling tools that select by type or region, such as analysis_select_by_type and analysis_find_in_region.

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

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

The description gives strong internal guidance about when to use compact=True versus the plain list, explaining the cap and the unreliable log-stream warning. However, it does not explicitly state when to prefer this tool over alternatives like entity_list, selection_filter, or analysis_select_by_type, leaving tool-selection guidance mostly implicit.

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

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

Annotations already mark the tool as read-only, and the description adds useful behavioral context beyond that: the MAX_LIST_LIMIT cap of 5000 and the fact that only compact=True reports total/truncated. It also notes that results are returned with handles. No contradiction with annotations.

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

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

Three short sentences with the core behavior front-loaded, followed by the cap/truncation caveat. The 'as with analysis_select_by_layer' shorthand avoids duplicating documentation, 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 read-only list operation with a fully described input schema and an existing output schema, the description covers the remaining runtime constraints: result cap, truncation reporting, and handle inclusion. It does not discuss ordering or multi-type queries, but those are not essential 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 baseline is 3. The description mostly restates the compact behavior already documented in the schema ('only shape that reports truncation') and adds no new meaning about fields or entity_type values 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 opening sentence uses a specific verb ('Get'), a resource ('all entities'), and a selection criterion ('specific type'), and the handle-return note clarifies exactly what the agent receives. Naming analysis_select_by_layer as the analogous tool helps place it, though the distinction is not fully spelled out.

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

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

The description implies the natural use case: fetching all entities of a given entity type. It references analysis_select_by_layer, signaling a sibling family, but it never states when to prefer this tool over alternatives like entity_list, selection_filter, or analysis_select_by_layer, nor when it should not be used.

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 provided, the description carries real load: it discloses that the block carries an invisible ITEM attribute, that the layer is auto-created from the arch layer set, that size is nominal rather than a standards value, and critically that all refusals occur before any write (atomicity). This is substantive behavior an agent would not learn from the annotations.

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

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

Two tight paragraphs with the primary action front-loaded and no filler. Slightly dense in the second paragraph (size vs outline distinction) but each sentence 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?

An output schema exists, so return-value explanation is correctly omitted, and the description covers name sourcing, layer behavior, size basis, and refusal conditions. The only gap is the absence of explicit sibling routing, which is a minor incompleteness for a write tool with many insertion neighbors.

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 schema already documents x, y, rotation, and the catalogue name. The description adds the item footprint/size semantics but no per-parameter syntax or format detail 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?

States a specific verb and resource: 'Define the item's block ARCH_<NAME> once, insert it on the furniture or sanitary layer.' The scope (catalogue block on a plan layer) clearly separates it from generic siblings like block_insert or std_part_insert, and the schema ties the name to arch_catalogue_list.

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

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

It implies usage by stating what the name must be and by describing the refusal path for unknown names, but it never explicitly says when to choose this over block_insert, pid_symbol_insert, or std_part_insert. The catalogue route to obtaining names is only implied via the schema 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?

Beyond the readOnlyHint annotation, the description discloses the exact catalogue size (20 items: 13 furniture, 7 sanitary), clarifies that sizes are nominal catalogue dimensions rather than standards values (flagged per-row via size_basis), and states the two refusal conditions with the returned list. This is meaningful behavioral context not present in structured fields.

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

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

The row-columns list is front-loaded and dense. The middle paragraph on size_basis straddles usefulness and verbosity, but it earns its place by preventing an agent from treating the sizes as standard values, and the refusal sentence is compact.

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 formatting, though it usefully summarizes columns. It covers the catalogue size, size-basis caveat, and refusal cases. The main missing piece is when to prefer this tool over related architecture tools, but for a simple read tool that gap 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?

Schema description coverage is 100%, so lang, query, and family are already fully documented, including query's case/diacritic-insensitive word matching. The description adds only the refusal behavior for unsupported family and lang values, which slightly reinforces the valid-input boundary but does not add new semantics.

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

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

The description states a concrete read operation and enumerates the returned row fields (name, family, labels, nominal size, block name, layer), so an agent knows this retrieves the architecture catalogue. It does not explicitly contrast itself with the sibling arch_catalogue_insert, but the listing/read nature is clear from the name and content.

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

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

There is no explicit 'when to use this vs alternatives' guidance. The refusals paragraph describes error behavior for invalid family/lang, not selection criteria, and no sibling tool is named as an alternative. Usage is only implied by the tool name.

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 carry destructiveHint=false, so the description does the heavy lifting and delivers: row ordering, the ISO 129-1 non-duplication rule, the server's own spacing defaults (10 mm then 8 mm) flagged as non-standard, and the temporary DIMSCALE swap that is restored afterwards. These are exactly the behavioral details an agent cannot get from structured fields.

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

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

The main idea is front-loaded and nearly every sentence carries unique information (defaults, restoration behavior, refusals). It is dense and the broken-line layout makes it slightly harder to scan, but there is little 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 an output schema present, return values need no explanation, and the description still covers behavior, defaults, side effects (DIMSCALE restore), and failure modes. Nothing an agent needs to call 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?

Schema coverage is already 100%, so 3 is the baseline, but the description adds real meaning: it clarifies that each chain is drawn at DIMSCALE = `scale` (returned as `dimscale`), that default spacing values are drafting choices, and that sides are validated against unknown/repeated values.

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 domain resource — the three exterior dimension chains of an architectural plan — and implies the producing verb ('as real DIMENSIONs'). It is clearly distinguishable from generic siblings like dimension_linear or dimension_aligned, but never explicitly contrasts itself against them.

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

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

It gives concrete preconditions and exclusions ('Refused by name: a drawing with no walls, an unknown or repeated side, a non-positive scale, offset or step') and explains the nearest-first row ordering. It stops short of routing the agent away from sibling dimension tools by name, so it is clear context without 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 carry only destructiveHint=false, so the description does real work: it states that all refusals occur before any write (validation-first, non-destructive on failure), which layer supplies the center linetype, where bubbles are placed, and that sizes are server-declared paper mm rather than a standards value. It stops short of stating idempotency or what happens to pre-existing grid entities, but the failure semantics are unusually explicit.

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

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

Three tight paragraphs, front-loaded with what gets drawn, then convention, then refusal conditions. The refusal enumeration is long but each item is a distinct error case with no filler, so it earns its space.

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

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

An output schema exists so return values need no explanation, and the description covers layer sourcing, sizing semantics, labeling convention, and failure modes. Minor gaps remain around layer names/prerequisites and whether callers must pre-create those layers, but overall it is complete for a 2-required-param drafting 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 the baseline is 3, but the description meaningfully extends it: it explains that labels override the default numbering per position in given order, clarifies the mm-vs-paper-mm relationship for scale, and enumerates the specific invalid values that trigger refusal for scale/extension and label lists.

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

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

Specific verb+resource: creates axis lines with end bubbles and labels on the arch grid/symbol layers. The detail about center linetype origin, bubble size, and numbering scheme makes it unmistakably distinct from siblings like centre_marks, arch_dimension_chains, or dimension_auto.

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

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

Usage is implied by the content (this is the tool for setting out a structural grid), but there is no explicit when-to-use or when-not-to-use guidance, and no alternative sibling is named for cases where the agent might want dimensions or centre marks 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?

Far exceeds the minimal annotation (destructiveHint=false). It discloses the geometric effect (opening removes its width from both wall faces, jambs close each edge), door vs window rendering (90° leaf, quarter-arc swing; frame + two glazing lines), that the ACADMCP_ARCH record sits on the leaf/frame for schedule read-back, and a detailed set of refusal conditions. This is unusually rich behavioral disclosure 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-loads the action ('A door or a window in a wall already drawn...'), then the geometry, then the refusal conditions. Dense but every clause carries information; the refusal enumeration is long yet each entry is a distinct failure mode.

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. For a complex 12-parameter mutation tool, the description covers geometry, validation, and persistence (xdata for schedules), leaving no material gap for an agent to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine conceptual meaning: it explains that the door leaf length equals the opening width and that the hinge is on `hand` with the arc on the `swing` side, tying these params to drawn geometry beyond 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+resource: it creates a door or window opening in an already-drawn wall identified by id, and redraws the wall cut. This is unmistakably distinct from arch_wall (which draws the wall) and from other geometry 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 prerequisite is explicit ('a wall already drawn, found by its id'), and the refusal list effectively delineates when the call will fail (wall id not on drawing, id already drawn, opening exceeds segment, overlaps another opening, runs into a junction). It does not name a sibling alternative explicitly, 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?

Annotations only carry destructiveHint=false, so the description carries the real burden and does so richly: validation happens before the transaction opens, a refusal names the offending path, drawing-level refusals and cancelled requests roll back (under an anyio shield), and the result includes each step's own result, the wall engine's omitted list, and three arch_* critique focuses. This is far beyond what the annotation discloses.

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

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

The purpose is front-loaded in the first sentence and each subsequent paragraph adds distinct information (validation/rollback semantics, then refusals, then sibling exclusion). The long refusal enumeration is dense rather than padded, though it could be tightened into a more scannable list.

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

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

For a complex, destructive-adjacent compound creation tool with sparse annotations, the description covers the transaction lifecycle, validation timing, rollback behavior, cancellation handling, result contents and sibling boundaries. An output schema exists and the description still notes what the result carries, so nothing an agent needs to invoke it correctly is missing.

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

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

With a single parameter at 100% schema description coverage the baseline is 3, but the description genuinely enriches the spec beyond the schema text: it explains that room areas are measured off the walls just drawn and never typed, and enumerates refusal conditions tied to specific spec fields (arc segment in a wall axis, overlapping openings with both ids named, unknown chain side or schedule kind).

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

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

Opens with a specific verb and resource: a whole plan drawn inside one transaction, then enumerates exactly what is produced (walls, hosted doors/windows, stairs, room labels with measured areas, dimension chains, schedules). It also explicitly separates itself from siblings by naming arch_catalogue_insert, arch_grid and arch_symbol as distinct tools, so an agent can route correctly 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 description makes clear this is the one-call path for an entire plan and names the adjacent tools that handle catalogue furniture, grid and symbols separately, which is genuine routing guidance. It stops short of an explicit when-to-use-this-vs-incremental-arch_wall/arch_opening statement, so an agent must infer the bulk-vs-piecemeal tradeoff.

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

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

Goes well beyond the minimal destructiveHint=false annotation by describing exactly how area is computed (reads wall faces on the wall layer, net of thickness and columns), how doors/windows affect room separation, what gets written (label text and ACADMCP_ARCH xdata), and the one-label-per-face idempotency 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?

Front-loads the action, then explains mechanics, then lists refusals. Slightly long, but every sentence is informative. Minor density could be improved but no wasted 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?

For a 7-param mutation tool with no output schema in description, all critical aspects (inputs, side effects, downstream consumption by arch_schedule, refusal cases) are covered. Complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning: lang values (en, tr) with numeric format example, area is never typed (x,y only), and room_id ties to a record written onto the name text. Adds value beyond schema descriptions.

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 (Label) and resource (the room around x,y) and specifies what the label contains (name, number, MEASURED area). It clearly distinguishes itself from siblings like arch_rooms_detect (read plans drawn by other means) and arch_schedule (reads records).

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 lists refusal conditions (unknown lang, invalid number/name, duplicate room_id, point in no closed face, point in wall, already labeled room) and points to the alternative arch_rooms_detect for plans drawn by other means. This is thorough when/when-not guidance.

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

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

Annotations only declare readOnlyHint=true; the description adds substantial behavior beyond that: the line-splitting/face-measurement algorithm, the 600 mm thin-face heuristic, confidence scoring rules, label conflict reporting, and the guarantee that arcs/bulges/blocks are listed in `skipped` rather than silently dropped. This is exactly the extra context annotations cannot carry.

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

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

Dense and front-loaded with the core purpose first, then exclusions, confidence, and refusal cases. It is long, but nearly every sentence carries operational information; minor tightening is possible.

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 analysis tool with a full output schema, the description covers purpose, failure modes, confidence semantics, and skipped-entity handling. An agent has everything needed to call it and interpret the result.

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, but the description adds real meaning: it explains the default WALL/DUVAR layer-matching rule and the refusal behavior when `layers` is omitted or names a missing layer, and ties `min_area` to the filtering behavior.

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 ('Read the rooms of a plan') and immediately scopes it to both native and foreign/plain-line plans. Clearly distinguishable from write-oriented siblings like arch_room or hatch_add_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?

Gives strong preconditions: read `confidence_min` before trusting a foreign plan, read `skipped` before trusting `count`, and lists explicit refusal cases (unknown named layer, no WALL/DUVAR layer). It lacks explicit 'use X instead' routing to siblings, so it stops short of a 5.

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

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

With only destructiveHint=false in annotations, the description carries the load well: it discloses the destructive-safe read nature, the row source, untagged-opening auto-numbering, empty cells instead of defaults, the 198-row ceiling, and the native vs composite representation outcome.

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

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

Front-loaded with the core action and the key constraint (records, not caller input) before enumeration of details. Dense but every clause carries information; slightly long, yet nothing is redundant filler.

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

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

An output schema exists, so return values need not be described, and the definition still covers data source, refusal modes, and representation output. It stops short of covering edge behavior such as placement conflicts, but is otherwise complete for a 5-parameter, non-destructive generation 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% and the schema already documents x, y, kind, lang, and scale. The description adds context about the K1/P1/D1/W1 tag convention and decimal-comma semantics for 'tr', but supplies no new syntax or format detail for the remaining parameters, 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+resource ('Draw a door, window or room schedule as a real TABLE') and clarifies it is a read of existing drawing records, distinguishing it from write tools like arch_wall/arch_opening/arch_room and from bom_table.

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?

Establishes clear prerequisites and context: rows come only from existing ACADMCP_ARCH records, and it enumerates refusal conditions (unknown kind/lang, nothing of that kind on the drawing, >198 rows). It does not, however, explicitly compare itself to near alternatives such as bom_table or data_extract.

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 destructiveHint=false, so the description carries the burden and does so well: it discloses label placement (2.5 mm × scale), the Blondel rule semantics (2R + G against 600-650 mm, reported not enforced, ok:false rather than refusal), and a precise pre-draw refusal list including stair-id collision and geometry constraints. This is exactly the kind of behavioral context annotations cannot express.

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

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

Front-loaded with what is drawn, then constraints, then refusals — a sensible order. It is on the verbose side (four dense paragraphs), but nearly every sentence carries a distinct constraint or rule, so little is wasted.

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

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

With 12 parameters, 7 required, and an output schema present, the description need not restate return values, and it does supply the refusal conditions and the one notable reported value (blondel). It stops short of stating units/coordinate assumptions beyond what the schema already documents, but nothing critical for a correct call is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains the riser-count minimums (2 straight, 4 for L/U, two per flight), the relationship of risers/going/riser_height to the reported Blondel value, and that the label scales with the scale parameter.

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

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

The description names a specific resource and the exact geometry produced: 'A stair in plan: every riser as a line, the outline, the walking line with its arrow.' An agent can immediately distinguish this from siblings like arch_wall, arch_opening, or entity_create_line 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?

Usage is implied by the refusal list ('Refused before anything is drawn: ...'), which tells the agent what inputs are invalid, but the description never states when to reach for arch_stair versus alternatives such as arch_plan_from_spec or arch_catalogue_insert. No positive when-to-use guidance or alternative routing is given.

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

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

Annotations only declare destructiveHint=false and a title, but the description adds substantial behavioral context: sizing semantics (paper mm × scale, not standard values) and a full list of refusal conditions that all occur 'before any write'. This atomicity guarantee is exactly the kind of write-safety detail an agent needs and goes well beyond the annotations.

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

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

Front-loaded with the purpose, then a sizing note, then the refusal list. Dense but every clause carries information; the long refusal enumeration is justified because it defines the tool's contract. Slightly sprawling but not wasteful.

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

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

An output schema exists, so return values needn't be explained, and the description covers kinds, sizing, and validation thoroughly. The only gap is the lack of explicit alternative-routing against sibling tools, which leaves the agent to infer which symbol tool to pick.

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, but the description adds real meaning beyond the schema: it explains that sizes are the server's declared drafting sizes (16 mm north-arrow circle, 10 mm bubbles) rather than standards values, and it ties each refusal condition to specific parameter constraints (unknown side, non-finite level, invalid lang).

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+target: 'Draw one architectural symbol on the arch symbol layer.' This clearly distinguishes it from the many other symbol/geometry tools (pid_symbol_insert, weld_symbol, centre_marks, arch_wall) 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?

The description enumerates the four kinds (north_arrow, section_mark, level, elevation_mark) and their refusal conditions, which implies the intended contexts. However, it never routes the agent explicitly: there is no 'use X instead' guidance against close siblings like section_line, weld_symbol, or pid_symbol_insert, so alternative selection 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?

With only destructiveHint=false given, the description carries the burden and delivers: junction resolution semantics (L/T/X), redraw-and-listing of affected walls under `redrawn`, the ACADMCP_ARCH record for later id lookup, and a thorough enumeration of pre-draw refusal conditions. This is unusually rich behavioral disclosure.

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?

Dense but front-loaded: the core action comes first, then junction behavior, then mutations, then refusals. Every sentence encodes a rule, though the prose is heavy enough that it could be tightened without losing meaning.

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

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

An output schema exists, so return-shape explanation is unnecessary, and the description still covers the one return detail that matters (`redrawn`). For a junction-resolving wall tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents `walls` and `poche`. The description still adds meaning beyond it: thickness must be positive, axes need 2+ points with no zero-length segment, justification/material values are validated against named lists, and ids persist via the ACADMCP_ARCH record.

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

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

The opening sentence states a specific verb (add) and resource (walls) plus the scope (the plan network already on the drawing) and the side effect (resolve every junction). It is clearly distinguishable from siblings like arch_opening, arch_stair, and entity_create_line.

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

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

Usage is well-framed as an operation on an existing plan network, and the long refusal list effectively communicates when the tool will not act (duplicate ids, degenerate axes, sub-5° mitres, curved walls). It does not explicitly name competing sibling tools, so it stops short of a 5.

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

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

Annotations only give destructiveHint=false; the description carries the real disclosure burden and does so well, covering idempotency via the ACADMCP_MECH payload (renumbered: true), and enumerating three refusal conditions plus the guarantee that refusals occur 'before the first entity' (atomicity). It stops short of describing layer/permission requirements.

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 entity it creates, then rerun semantics, then refusals — a sensible order with almost no filler. The hard-wrapped lines are cosmetic noise, and the refusal paragraph is dense but earns its place.

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

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

For a 9-parameter mutation tool with an output schema, the description covers the non-obvious behavior an agent needs: idempotent renumbering, failure modes, and atomicity. Return values need not be explained given the output schema, so remaining gaps are 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?

With 78% schema coverage the baseline is 3; the description adds real meaning beyond the schema by tying 'item' to bom_extract numbering and defining 'targets' as the handles a rerun renumbers by. The radius/numeral ratio rule is also clarified in-language, though leader and layer/layout stay 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?

The first sentence states a concrete verb+resource ('One ISO 6433 item reference: a numbered balloon, a leader, and a dot on the item'), which unambiguously distinguishes it from siblings like bom_extract, bom_table, or mech_dimension_part. An agent can identify the tool's output entities 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 explains the re-run case ('running the balloon pass again after the bill of materials is regrouped *renumbers* the existing balloon'), which is useful usage context, but never states when to call this versus siblings such as bom_table or bom_extract, nor any prerequisite (e.g. BOM must exist first). Usage is implied rather than routed.

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 destructiveHint=false, so the description carries most of the burden — and does. It discloses that sheet size is verified from the written PDF's /MediaBox rather than assumed, lists the exact pre-write refusal conditions (non-pdf format, empty layouts, nonexistent layout, bad file_pattern, disallowed output path), and defines the error contract (`mediabox_mm: null` plus `error`). That is rich, non-obvious behavioral context 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?

Front-loaded with the one-line purpose, then output shape, then refusal rules — a logical order with no filler sentences. Some inline bold and parenthetical detail (points → mm, 0.5 mm tolerance) thicken it, but each clause adds operational meaning.

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 4-parameter batch export tool with an output schema already present, the description supplies everything the missing pieces would otherwise hide: what gets written, how success is verified, what is rejected before writing, and how per-sheet failures surface. An agent can call this correctly without further documentation.

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, but the description adds real constraint semantics: `file_pattern` must contain `{layout}` when plotting multiple sheets and must not contain a path separator, and `layouts` naming governs whether Model space is included. Those are behavioral constraints on parameters that the schema alone does not express.

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 operation — AutoCAD PUBLISH producing a PDF set — and ties it to the sibling mechanism `drawing_export_pdf(layout=…)`, making clear this is the batch wrapper around a single-sheet export. The name `batch_plot` is immediately grounded by 'PDF set' and 'one row per sheet', so an agent can separate it from drawing_export_pdf 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?

Usage context is clear: publish many layouts at once, omit `layouts` for every paper-space layout, include 'Model' only when named. The link to `drawing_export_pdf(layout=…)` implies the alternative for single-sheet work, but the description never explicitly says 'use drawing_export_pdf for one layout' nor states when neither should be used.

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 mutation hint (readOnlyHint=false), the description discloses that originals remain in model space, that unresolved handles are surfaced in `skipped` rather than silently dropped, and that a fully-unresolved call fails instead of creating an empty definition. These side-effect and error-handling details materially shape agent expectations.

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

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

Three sentences, front-loaded with the core purpose, and each subsequent sentence adds distinct information: non-consuming semantics, alternative tool routing, and error-handling behavior. No filler or restatement of the title.

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

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

For a mutation tool with an output schema, the description covers creation semantics, side effects on source entities, the placement workflow, and failure modes. The existing output schema handles return-value documentation, so nothing an agent needs to call 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%, so the baseline is 3. The description adds real value by explaining the behavior of the handles parameter (unresolved ones go to `skipped`, all-unresolved fails), which goes beyond the schema's bare 'List of entity handles to include in the block.' name, base_x, and base_y appropriately rely on the schema at full coverage.

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 states a specific verb+resource: 'Create a new block definition from existing entities in the drawing.' The scope is sharpened by distinguishing this from AutoCAD's BLOCK command (non-consuming) and from siblings like block_insert (placement) and block_explode, so an agent can tell them apart.

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 follow-up alternative: 'use `block_insert` to place copies, and delete the originals yourself if you want the command's behaviour.' It also notes cross-engine portability ('Works on both engines'), giving an agent clear context for when and how to chain this call.

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

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

Annotations only supply readOnlyHint=false. The description carries the full behavioral load: all-or-nothing validation before any write, the exact refusal cases (malformed primitive/ATTDEF, non-finite base point, name clash, anonymous '*' name, missing layers), overwrite replacing contents while preserving INSERT references, ByBlock geometry inheriting INSERT layer colour/lineweight, and the layers_created/replaced outputs. This is 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?

Dense but front-loaded, with the atomicity guarantee first and refusal modes enumerated compactly. Every sentence carries information, though the run-on refusal list is slightly heavy to parse in one pass.

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 tool with 7 params, atomic-write semantics and an output schema, the description covers the transaction behavior, failure modes, overwrite semantics and the follow-up insert call. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real semantic value: overwrite replaces the *contents* so existing INSERTs keep pointing at the name, and create_layers creates then lists the layers in layers_created rather than refusing. It does not re-explain name/base_x/base_y 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?

Opens with a specific verb+resource ('Create a block definition with attribute definitions from typed specs') and distinguishes itself from siblings like block_create_from_entities and block_insert, even naming the latter as the downstream consumer. An agent can identify the operation 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?

Explicitly routes the agent: use overwrite=true to replace contents, create_layers=true to auto-create missing layers, and use block_insert to place the block afterwards. It enumerates refusal conditions clearly, though it does not contrast against block_create_from_entities, the closest alternative for making blocks from existing entities.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds substantial behavioral context beyond that: how ATTRIBs become TEXT/MTEXT, invisible/constant attribute handling, layout placement, no-undo semantics via drawing_undo/transaction, headless capability restrictions, and refusal cases with nothing written.

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

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

The core action is front-loaded in the first sentence, followed by dense but relevant behavioral detail. It is appropriately sized for a complex destructive operation, though some return-value detail overlaps with the output schema, keeping it from a perfect 5.

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 destructive nature, output schema, and multiple edge cases, the description covers refusal conditions, side effects, undo caveats, return fields, and engine differences. An agent has everything needed to invoke it correctly and anticipate failures.

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 handle parameter is fully described in the schema as 'Block reference (INSERT) entity handle'. The description references the handle in refusal conditions but adds no syntax or format detail beyond what the schema already provides, so 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?

States a specific verb and resource: 'Explode a block reference into its component entities, keeping its attribute text (the Express Tools BURST rule, on both engines).' It contrasts with AutoCAD's plain EXPLODE and makes the attribute-retention behavior central, which distinguishes it from sibling block_* 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 clearly applies to block reference handles and lists when the operation is refused (non-block handle, nested reference, xref, MINSERT, opaque member). However, it does not explicitly name alternative tools such as block_get_attributes or say when to prefer this over them, so it stops short of full when/when-not/alternatives guidance.

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

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

The description discloses a meaningful behavioral limitation: only the backend's default 200 INSERTs are scanned, and the compact envelope's total counts only references found within that scan. This adds real context beyond the readOnlyHint annotation and helps set accurate expectations about completeness and truncation.

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

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

The description is compact, front-loaded with the core purpose, and the follow-up sentence about the scanning limit earns its place. There is no redundant restatement of the title or schema.

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

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

For a read-only query tool with a rich input schema and an output schema, the description covers the essential behavioral caveat, return-shape nuance, and purpose. Nothing critical is missing for an agent 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?

The input schema already provides full descriptions for all three parameters, including the compact envelope shape and the fields projection syntax. The description adds some nuance about the compact total field, but it does not meaningfully explain parameter usage beyond what the schema already documents, 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 action—'Find all insert references to a specific block definition'—with a clear verb and resource. It naturally differentiates itself from sibling tools like block_list, which lists block definitions, by focusing on references to a definition.

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

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

There is no explicit guidance about when to use this tool versus alternatives, nor any mention of when not to use it. The sibling set includes block_list and entity_list, but the description never explains how this tool relates to them or when one should be preferred.

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 covered. Beyond that, the description adds real value: it documents the return shape as a {TAG: value} dict and discloses the subtle edge case that multi-line attributes are returned with `\P` separators (AutoCAD TextString) on both engines — a genuine behavioral disclosure an agent would not get from 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?

Two short sentences, front-loaded with the core action and return type, followed by one narrowly scoped edge-case note. Nothing is redundant and nothing is wasted.

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

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

An output schema exists, so return values needn't be spelled out, and the readOnly annotation covers safety. Combined with the description's return-shape and multi-line notes, an agent has what it needs; only explicit sibling routing (vs. block_set_attributes/entity_get) is missing.

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

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

Schema description coverage is 100% and the single `handle` parameter is documented as a 'Block reference (INSERT) entity handle'. The description's reference to 'a block reference' restates rather than extends that; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get all attribute values from a block reference') and even specifies the return shape ({TAG: value} dict). The 'Get' vs. the sibling block_set_attributes is implicitly clear, but the description never explicitly names or distinguishes itself from that sibling, 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?

No statement of when to use this tool versus alternatives such as entity_get, block_list, or block_set_attributes, and no prerequisites (e.g. the handle must reference an INSERT with attributes). The multi-line note is behavioral, not usage guidance.

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

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

Annotations only provide readOnlyHint=false, so the description carries most of the behavioral burden and does so well: it discloses the coercion rules (int/finite float become plain digits, strings written as-is on one line), the explicit rejections (null, booleans, lists, objects, named by tag), and that values for undefined tags are silently ignored. It stops short of describing transaction/permission requirements or atomicity with respect to the drawing state.

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

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

The core action is front-loaded in the first sentence, and the second paragraph is dense but every clause carries a distinct rule (refusal cases, coercion, ignoring unknown tags). It is longer than ideal but not padded.

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

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

With an output schema present, return values need no explanation, and the description adequately covers the write-refusal and value-coercion semantics that an agent must know before calling. The main gap is that mutation side effects and interactions with siblings are left implicit.

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

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

Schema description coverage is 100%, so the baseline would be 3, but the description genuinely adds semantics beyond the schema's '{TAG: value}' for attributes — it specifies the accepted value types and the exact conversion behavior. No added meaning is given for x, y, layer, scale, or rotation, which the schema already covers.

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 names a specific verb and resource ('Insert a block') plus the optional attribute-setting capability, which separates it from block_define and block_set_attributes. It does not, however, distinguish itself from the closely related sibling entity_create_block_ref, so an agent must still infer which insertion path applies.

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

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

The description implies usage through its refusal conditions (undefined/layout block names are rejected) but never states when to choose this tool over block_define, entity_create_block_ref, or block_set_attributes. Context is implied rather than 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 readOnlyHint annotation, the description discloses a key behavioral trait: the result is never truncated and the compact envelope always reports truncated=false. This is valuable runtime context that is not available from annotations or the schema alone.

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

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

Two tightly written sentences. The first delivers the core purpose and expected fields; the second adds the most important behavioral caveat. No filler or repetition.

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

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

Given the read-only annotation, rich parameter schema with descriptions, and an output schema, the description covers the remaining essential context: output scope, non-truncation, and the compact envelope behavior. Nothing critical 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%, so the baseline is 3, but the description adds meaning by explaining what fields exist in the block definitions and by connecting the compact envelope to the never-truncated guarantee. This goes beyond simply repeating schema names.

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

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

The description explicitly states a specific action ('List'), a precise resource ('all block definitions in the drawing'), and the returned fields ('name, origin, attribute count, entity count'). It clearly distinguishes this from filtered or reference-based block 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?

The description makes clear this returns the whole block table and never truncates, which sharpens when to use it. It does not explicitly name alternatives or exclusions, but the purpose and scope are unambiguous enough for a selection decision.

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 provide readOnlyHint=false, so the description carries most of the behavioral load and does so well: it discloses pre-write validation (bad types refused naming the tag before anything changes), that unknown tags are silently ignored, and the updated_tags reporting contract. It falls short of stating permissions or failure modes on a missing/invalid handle.

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 paragraphs, front-loaded with the core action and then the value rule, with essentially every sentence carrying invocation-relevant information. Phrasing is slightly idiosyncratic ('bursts', 'on both engines') but not wasteful.

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 an output schema and minimal annotations, the description supplies the constraints, atomicity guarantee, value-type rules and round-trip consistency an agent needs to call it safely. Nothing material is missing.

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

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

Schema coverage is 100%, so the 3 baseline applies, but the description meaningfully exceeds it: it defines which value types are writable (strings/numbers) versus refused (null/booleans/lists/objects), how multi-line values are encoded via 'Line1\\PLine2', and how unknown tag keys are treated. Only the handle parameter is left entirely to 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+resource ('Update attribute values in a block reference') that is unmistakably distinct from the read-side sibling block_get_attributes and the creation-side block_insert. The scope is narrow and the agent can select it without opening another schema.

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

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

Usage is strongly implied by the mutating verb and the discussed constraints (values are refused before anything changes), but there is no explicit routing guidance such as when to prefer block_insert/block_define or what preconditions the reference must satisfy. The mentions of block_insert, block_get_attributes and block_explode are consistency references, not alternatives for the agent to choose between.

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 readOnlyHint=true, the description discloses that it never modifies the drawing, how each row's provenance is reported (xdata vs attributes), that payload-less/attrib-less blocks are skipped rather than guessed, that skipped counts them, and the exact `truncated` invariant. This is unusually rich behavioral context for a read 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 purpose, then provenance, then paging semantics. Dense but every sentence carries information; the parentheticals ('what `std_part_insert` writes', 'not taken as a cap') are somewhat verbose but justified.

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

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

An output schema exists, and the description still supplies the non-obvious return semantics (row source, skipped count, truncated invariant) plus refusal behavior. Nothing an agent needs to call 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?

Schema coverage is 100% and the schema already documents all four params, but the description adds real meaning: the rationale for limit=0 (a capped list prints a wrong QTY, not a shorter one) and the iff-relationship between `limit` and `truncated`. It adds less on layer/columns/group_by, which the schema covers.

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 ('walk the INSERTs and return the ISO 7573 item rows') and immediately distinguishes itself from the sibling that renders them ('`bom_table` is what draws them'). An agent can separate extract vs. draw 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?

Explicitly says the whole drawing is read by default and why the entity_list 200-page is paged through rather than treated as a cap, then states when to pass `limit`. It also names the refusal cases (unknown column or group_by field), giving clear use/avoid conditions.

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

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

Annotations only carry destructiveHint=false, so the description carries the burden and does so well: it discloses the two representation modes (native ACAD_TABLE vs composite rules+MTEXT with handle pointing at the first child), the growth direction semantics, and the four refusal cases. That is exactly the non-obvious behavior an agent needs.

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

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

Front-loads the core action and size, then branches to direction, rows/omission, representation, and refusals in a compact sequence. The direction sentence partially repeats the schema's own description, which is minor waste but not bloat.

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

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

For an 11-parameter tool with an output schema (so return shape needn't be explained) and thin annotations, it covers the decision-critical pieces: source of rows, orientation behavior, representation output, and refusal modes. Remaining gaps are the anchor/origin parameter semantics.

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

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

Schema description coverage is only 36% across 11 params, and the description compensates for direction, rows, and columns (via the unknown-column refusal) but says nothing about at_x/at_y, origin_x/origin_y, size, layout, row_height, or orientation. Partial coverage leaves several parameters to be inferred from names alone.

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 ('Draw the ISO 7573 item list as a real TABLE entity'), names the exact geometry (180 mm, title-block width) and placement (above the title block), distinguishing it from sibling bom_extract, which it only invokes as a data source.

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

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

Explains the key branch: pass `rows` to draw an existing list, omit it to run bom_extract first, plus when to use direction='up' per ISO 7573. It also enumerates refusal conditions. It does not contrast against other table/annotation siblings (entity_create_table, balloon_add), so it falls short of explicit alternatives.

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 destructiveHint=false annotation, the description discloses that handles may arrive in any order, that chain ordering is handled internally, and that non-closing chains are refused with an error naming the gap coordinates. It does not explicitly state whether original entities are modified or a new polyline is created, but the annotation reduces that risk.

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 carry substantial, non-redundant information. The primary purpose is front-loaded, and every sentence earns its place without filler or repetition of the schema.

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

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

For a two-parameter tool with a full output schema and a safety annotation, the description covers the essential semantics: input, ordering, closure requirement, and failure behavior. A minor gap is the lack of explicit guidance on where the resulting polyline is created or how it relates to the original entities, but this is not critical 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 coverage is 100%, so the schema already documents both parameters. The description adds meaningful semantic detail by clarifying that handles are order-independent and by tying the close requirement to the tolerance/rejection behavior, which enriches the agent's understanding beyond raw schema properties.

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 outcome: 'Chain the given entities into one closed polyline.' It also clarifies the tool's unique responsibility—handling arbitrary handle order—which distinguishes it from merely exporting or tracing boundaries.

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

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

The description implies when to use the tool: when you have unordered entity handles that need to be chained into a closed boundary. It does not explicitly name alternatives or exclusion conditions, such as when boundary_trace would be preferable, so it falls short of full guidance.

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

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

The description goes well beyond the annotations by explaining key behaviors: nearest-enclosing-loop selection, edge splitting on crossings, refusal when no loop is found, and error messaging that names gaps. This gives the agent important expectations that the annotations alone do not convey.

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

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

The description is compact and front-loads the core action first, then adds edge-case behavior in short, informative sentences. Every sentence earns its place without 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?

Given an output schema is present and the annotations indicate a non-destructive operation, the description covers the essential invocation semantics, edge cases, and failure behavior. An agent has enough context to call this tool correctly.

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

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

Schema coverage is 100%, so the parameters are already well documented. The description adds some nuance around tolerance by describing the near-close gap failure mode, but it does not add substantially new meaning to the parameters 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 opens with a specific verb and resource: "create a closed polyline around a seed point" and names AutoCAD's BOUNDARY/BPOLY as the reference. The seed-point mechanism distinguishes it from the sibling boundary_from_entities, making its purpose unambiguous.

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

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

The description provides clear context for when to use the tool: when a boundary must be created from a seed point and when the nearest enclosing loop is the desired result. It stops short of naming explicit alternatives or when-not-to-use conditions, but the behavioral guidance is strong enough to guide selection.

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 extensive behavior beyond the safety annotations: power is never invented, panel inference flags `panel_inferred`, length is Manhattan distance with rounding, totals count power once per package, open items are listed, and refusals occur for invalid lang/allowance/section rules or unreadable drawings. It also explains the write side-effect (XLSX/CSV output) and the fallback when openpyxl is missing. This is far richer than the readOnlyHint=false / destructiveHint=false 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 front-loaded with a one-sentence purpose, then proceeds through rules, outputs, and refusals in a logical order. It is dense, but each sentence conveys a distinct rule or constraint. There is minor repetition around section rules and open items, but overall it is appropriately sized for a complex 7-parameter tool.

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

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

With an output schema present, the description need not explain return values. It covers prerequisites, defaults, validation refusals, output artifacts, and fallback behavior comprehensively. An agent has everything needed to invoke the tool correctly, including the read-only-on-drawings clarification against the write side-effect.

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 constraints beyond the schema: `lang` values outside tr/en/ru are refused, `allowance` outside 0-1 is refused, malformed `section_rules` are named by path, and `output` writes four named sheets plus CSVs. These details go beyond the schema's own parameter descriptions, though some panel_rule behavior is repeated from the schema.

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

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

The first sentence names a specific verb and scope: 'A cable takeoff: one row per electrical load, the shop's cable method made repeatable.' It clearly distinguishes this from generic extraction tools by focusing on electrical loads and a repeatable cable method. An agent can tell it apart from siblings like pipe_takeoff without opening the schema.

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

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

The description implies usage by describing the inputs it reads (P&ID, layout) and the output it produces, but it never explicitly states when to choose this tool over alternatives such as pipe_takeoff. No exclusions or 'when not to use' guidance are given. The context is clear enough to infer the tool's purpose, but routing guidance is absent.

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 destructiveHint annotation, the description discloses validation-first execution, typed error kinds, on_error semantics, dry_run behavior, verbose output behavior, and the nuances of atomicity across backends. This is far more than annotations alone provide and sets accurate expectations for side effects.

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

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

The description is long but every section earns its place given the tool's complexity: example, validation behavior, error model, atomicity caveats, exclusions, and sibling alternative. The core benefit is front-loaded, and the structure is skimmable with clear labels.

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 correctly focuses on behavior rather than return shapes. It covers success output, verbose mode, validation, dry_run, error typing, atomicity, and exclusions, making it fully actionable for correct invocation in a wide range of scenarios.

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?

Although schema coverage is 100%, the description adds deep semantics for steps, bind references, '$name.field' access, '$$' escaping, dry_run validation behavior, and on_error modes. The worked example makes parameter composition concrete, going well beyond the schema's field descriptions.

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 'Execute an ordered list of tool calls in ONE round trip,' which names a specific verb, resource, and key benefit. It also distinguishes itself from entity_batch_create by noting that tool is denser for many homogeneous entities, so the purpose is clear and differentiated from 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?

Explicit guidance covers when cad_batch is appropriate and when it is not: it states that raw command/LISP escape hatches and cad_batch itself cannot be called from a batch, and recommends entity_batch_create for large homogeneous sets. This gives an agent concrete routing rules.

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 destructiveHint=false, so the description carries nearly the whole load and does: it frames the operation as a write ('before the first entity is written'), lists six distinct validity refusals, notes the ocs_tilted_plane capability limitation, and warns against supplying remembered radii. That is unusually rich behavioral disclosure beyond structured fields.

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

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

It is dense but front-loaded with the purpose before the guidance, and the refusal list is scannable. Idiosyncratic asides like 'the classic silent wrong number' cost some space, but every sentence still carries actionable information.

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

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

With an output schema present, return values need not be described, and the description covers inputs, validation, layer behavior, and the ISO standard. Minor gaps remain (default layer when `layer` is null, what specifically gets created), but nothing critical 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: handles are preferred over centers because real centre/radius are read back, and style='lines' requires a radius. The mark-vs-lines and extension meanings are already in the schema, so it does not double up unnecessarily.

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?

It states a specific action and target: placing centre marks on the CENTER layer matching ISO 128-23's dash pattern. The verb is implied rather than stated outright ('Centre marks on the CENTER layer'), but the resource and standard are unambiguous and no sibling tool does the same thing.

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

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

The description gives real selection guidance: prefer `handles` so radii come from the drawing via entity_get rather than being restated, and it enumerates the preconditions that cause refusal (neither/both input sets, non-CIRCLE/ARC handles, tilted planes, bad style, non-positive extension). It stops short of naming an alternative tool for the explicit-coordinate case, but the when-to-use logic 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?

Annotations already mark the tool as destructive, and the description adds valuable behavior beyond that: the operation is idempotent. It also explains the required ordering relative to finalization. No contradiction with annotations.

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

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

Three short sentences, each earning its place: the action, idempotency, and the required ordering. The most important behavior is front-loaded 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 single-parameter, optional-layer tool with an output schema and destructive annotation, the description covers the essential action, idempotency, and the key workflow dependency. Nothing critical is missing for an agent 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 the optional `layer` parameter is already documented as 'Layer to clear'. The description reinforces the default CONSTRUCTION layer but does not add significant semantic 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?

The description uses a specific verb ('Delete') with a clear resource ('every entity on the CONSTRUCTION layer'). It clearly distinguishes this scaffold-clearing operation from layer deletion and generic entity deletion tools among 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 explicitly states when this must be called: before `drawing_finalize`, to satisfy the `construction_left` critique. It gives solid contextual guidance, though it does not name alternatives or explicitly say when not to use it.

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