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

The annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is partly covered. The description adds useful behavioral context beyond the annotations, notably that the operation is undoable with Ctrl+Z and that the active DIMSTYLE controls style/size and is not modified by the tool.

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

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

The description is front-loaded with purpose, then structured into usage and per-type parameter guidance. Despite covering nine parameters and five dimension kinds, it avoids wasted sentences and the example makes the invocation pattern concrete.

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 complex kind-dependent parameter model, the description is complete enough for an agent to call the tool correctly. Return values are covered by the output schema, and the description covers creation, undoability, usage context, parameter mapping, and DIMSTYLE behavior.

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

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

Schema description coverage is 0%, so the description carries the full burden. It compensates excellently by mapping parameters per dimension type: linear, aligned, radius, diameter, and angular each get their required parameters, along with an optional layer and an example call.

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: 'Cria uma cota nativa (entidade DIMENSION) no espaço modelo.' This clearly identifies what the tool does and distinguishes it from generic drawing primitives, but it does not explicitly differentiate itself from the sibling tool dxf_add_dimensions.

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 'QUANDO USAR' section gives clear usage context: dimensioning distances between supports, diameters, radii, and angles directly in the open drawing. It does not state when not to use the tool or name an alternative such as dxf_add_dimensions, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutating nature is covered. The description adds useful format behavior (\P as the newline escape, width must be > 0) but says nothing about needing an active document, units, or how the insertion point relates to the box alignment.

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 an explicit QUANDO USAR marker, a compact parameter list, and a concrete example. Each element earns its place, though the parameter line is a terse enumeration rather than prose.

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

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

With an output schema present, return values need not be explained, and the description covers all five parameters plus the multiline use case. It omits document-state prerequisites and unit conventions, which is a minor remaining gap for a 5-param mutation tool.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it delivers: point is described as the insertion corner, width as a box width constrained to > 0, height as optional text height, and layer is named. It does not clarify the coordinate format or units for point/width, leaving a small gap.

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

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

The opening sentence gives a specific verb and resource in "Adiciona texto de várias linhas (MText)", and the qualifier "de várias linhas" implicitly separates it from the single-line sibling add_text. An agent can tell what entity is created 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?

"QUANDO USAR: notas e legendas" states a clear use context for this tool. It stops short of naming add_text as the alternative for single-line text or stating when not to use MText, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write/destructive profile is covered. The description adds no behavioral context beyond that — no mention of undo impact, layer-creation side effects, or overwrite behavior — but it is consistent with the annotations, so the lower bar applies.

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?

Well front-loaded: purpose first, then when-to-use, then parameters, then example. Dense but each element earns its place; the parameter list is slightly terse 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 need not be described. For a mutating text-creation tool the description covers purpose, usage condition, all five parameters, and an example, leaving only minor gaps around coordinate conventions and layer auto-creation.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does: it labels point as insertion, height as >0 in drawing units, rotation in DEGREES, and layer, plus a concrete call example. It does not clarify the point's coordinate dimensionality/order beyond the example.

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: 'Adiciona texto de linha única' (adds single-line text). The 'linha única' qualifier implicitly distinguishes it from the multiline sibling add_mtext, though that sibling is never named explicitly.

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

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

'QUANDO USAR: rótulos curtos (TAG, cota, nota)' gives an explicit when-to-use condition with concrete examples. It lacks a when-not clause or a named alternative (e.g., use add_mtext for multiline), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavioral context beyond that: it runs without AutoCAD and reports without inferences, which tells the agent results are deterministic and server-side. It says nothing about output shape, but an output schema exists, so the gap is minor.

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

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

Front-loads the purpose, then sections WHEN TO USE, parameters, and a concrete example, with no filler sentences. Well organized and appropriately sized, though the last line about AutoCAD could be folded in more tightly.

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 annotations covering the safety profile and an output schema presumably covering the return format, the description only needs to add scoping and usage, which it does via the when-to-use clause, parameter notes, and a worked example. Adequate for a read-only audit tool; only cross-tool disambiguation 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 0%, so the description must carry the load, and it largely does: it explains that snapshot must be complete, that allowed_types/expected_tags come from the project, and it supplies a limit range (1..500) that the schema does not constrain. Only the snapshot's internal field/filter structure is left undocumented, keeping it from a 5.

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

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

States a specific verb and resource (audits support-register TAGs) and enumerates the exact checks performed: duplicate TAGs, empty fields, expected register, and totals per line/type. It distinguishes itself from dimensioning tools via 'não dimensiona suportes', but never names the audit-family siblings (snapshot_support_register, compare_support_register, dxf_audit), so an agent must still guess which audit tool 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 'QUANDO USAR' block gives an explicit condition (register QA before delivery or Excel import) plus a negative boundary ('não dimensiona suportes'). It is clear context, but it stops short of naming an alternative tool, so it falls just below the routing-explicit 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'não altera nada'. It adds useful behavior beyond annotations: the return contents (count, types, sample handles, missing standard layers) and the limitation that it does not check internal block content.

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 text is well-structured and front-loaded: core purpose first, then usage, parameters, return details, limitation, and a concrete example. Every sentence serves a purpose 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 the tool's complexity, 0% schema coverage, and the presence of an output schema, the description provides all necessary context: parameter semantics, return format, and behavioral boundaries. An agent has enough information 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 0% schema description coverage, the description fully compensates by explaining all three parameters: allowed_layers accepts names or wildcard patterns with an example, ignore_layers has a clear default, and limit defines the maximum sample entities per layer.

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 ('Relata') and resource ('entidades do espaço modelo em camadas FORA do padrão informado'), with clear scope and no ambiguity. It distinguishes itself from general audit siblings by focusing exclusively on layers outside a given standard.

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 a clear 'QUANDO USAR' section with the exact scenario: design audit before delivery. However, it does not name alternative tools (e.g., dxf_audit) or state when not to use this tool.

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

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

Annotations already declare the read-only, non-destructive profile, so the bar is lower. The description adds genuinely non-obvious behavior: it works without AutoCAD, position_tolerance is in drawing units rather than a normative tolerance, and ambiguous TAGs are deliberately not matched. The matching semantics are valuable context not derivable 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?

Front-loaded purpose followed by clearly labeled WHEN TO USE, parameters, and a concrete example. Dense but every block earns its place; only minor redundancy between the first line and the parameters note.

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. For a snapshot-comparison tool it covers purpose, precondition, key parameter semantics, and matching behavior well; the only gap is the undocumented limit and allow_document_change parameters.

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

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

Schema description coverage is 0%, so the description carries the full parameter burden. It clarifies position_tolerance (drawing units, non-normative) and requires before/after to be 'completos', but leaves limit and allow_document_change entirely unexplained, covering only three of five parameters.

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

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

States a specific verb+resource ('Compara revisões por TAG') and enumerates the result categories (inserted/removed, displacements, changed attributes). This clearly distinguishes it from sibling snapshot_support_register and audit_support_register, which do not compare revisions.

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 'QUANDO USAR' section gives a concrete precondition (revisions of support registers with identical units/filters) and notes it runs without AutoCAD. It stops short of stating when-not-to-use or naming an alternative sibling, so it is clear context without explicit exclusions.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, which is consistent with a copy that mutates the document. The description adds value beyond that: the maximum of 500 copies, the linear-step placement rule, and a worked example. It stops short of saying which document/layer the copies land on, so it is not fully complete.

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

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

Front-loaded with the core behavior, then a scoped usage note, then parameters and an example. Every sentence carries information (step semantics, limit, formats) with no filler.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile. For a simple 3-param mutation tool the description supplies purpose, limits, formats, and an example. It is only slightly short of complete: handle semantics and any document/layer side effects are unstated.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it largely does: it documents all three parameters, gives the displacement vector format with the optional third component ([dx, dy(, dz)]), the count constraint (≥ 1), and a concrete call example. Only 'handle' lacks any format/meaning beyond its name.

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+resource ('copy an entity') and immediately adds the distinguishing semantics: each copy is offset by one displacement vector, forming a linear array. This differentiates it cleanly from siblings like move_entity (which relocates one entity) or insert_block. 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?

The explicit 'QUANDO USAR' section gives a concrete use case ('repeat an item at a constant step, e.g. supports every 3000') and a hard limit of 500 copies. It does not name an alternative tool or state when not to use it, but the context is clear enough to route correctly.

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

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

The annotations declare destructiveHint=true, but the description explicitly asserts 'Não é destrutivo' and describes idempotent, additive behavior. This is a direct conflict between the description and the structured annotation, which forces a 1 regardless of which side is factually correct.

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

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

Front-loaded with the action and its idempotency, then clearly sectioned into QUANDO USAR / Parâmetros / Exemplo. The dense constraint lists all earn their place, though the whole block is on the long side for a 3-parameter tool.

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

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

An output schema exists, so return values need no explanation, and the description covers creation semantics, idempotency, permitted parameters and an example. The one missing piece is which document context the layer is created in, which matters given siblings like set_active_document and list_documents.

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

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

Schema description coverage is 0%, so the description carries the full burden — and it does: it documents the forbidden characters for 'name', the valid color forms (ACI index 1-255 or named colors) and the linetype loading requirement including auto-loading of HIDDEN/CENTER/DASHED/PHANTOM. This meaning is available nowhere in 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 ('Cria uma camada') and adds the key behavioral fact that it is idempotent ('se já existir, não altera nada e avisa'). It does not, however, differentiate itself from the sibling 'dxf_create_layer', which an agent will need to disambiguate.

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 an explicit 'QUANDO USAR' clause placing the tool before drawing/inserting into a new layer, which is exactly the routing information an agent needs. It does not name an alternative or a when-not condition (e.g. how it relates to dxf_create_layer or list_layers).

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, it discloses that confirm=true is mandatory, that the operation is all-or-nothing, that a Ctrl+Z undoes it, and that a nonexistent handle aborts the whole batch with the missing handles listed in the error. That is unusually rich 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?

Front-loads the destructive warning, then when-to-use, flow, parameters and an example in a tight, well-ordered block. 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?

An output schema exists, so return values need no explanation, and the description covers preconditions, error behavior, and the confirmation flow. 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 0%, so the description must carry the load, and it does reasonably well: handles is a list of hex strings, dry_run previews what would be deleted, confirm gates the actual deletion, plus a concrete usage example. It stops short of documenting defaults or full type detail, but the critical semantics are present.

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

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

States a specific verb and resource (delete entities by handle) with scope clearly bounded. It does not differentiate itself from the near-identical sibling dxf_delete_entities, leaving an agent to infer which tool to pick between 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?

Explicitly states WHEN TO USE ('only when the user asked to delete') and lays out the required flow (dry_run first, then confirm=true). The alternative path is named and conditioned, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, covering the safety profile, and the description is consistent with them ('Desenha' implies document mutation). However it adds no behavioral detail beyond that — no mention of persistence, undo, units being inherited from the drawing, or interaction with the active document — so it earns only the baseline credit given annotations are 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?

Two tightly packed lines: purpose first, then a labeled 'QUANDO USAR' clause, then labeled parameters with an inline example. No filler, and the highest-value information is front-loaded.

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

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

With an output schema present, return values need not be described, and the description plus annotations together cover purpose, usage, parameters and safety. The only gaps are behavioral (mutation/undo/active-document effects) and the untranslated layer semantics — minor for a simple geometry primitive.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely does: it defines center as [x, y] or [x, y, z], constrains radius to > 0 in drawing units, identifies layer, and provides a worked call example. Only the meaning of the null/default layer and how coordinates map to the active document are left unstated.

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 ('Desenha um círculo') and the geometry siblings it complements (draw_line, draw_polyline) make the distinction obvious without opening a schema. An agent immediately knows this creates a circular entity.

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?

'QUANDO USAR: furos, bocais em planta, marcações' gives concrete use cases (holes, plan-view nozzles, markings) that tell the agent when this tool fits. It stops short of naming an alternative or an exclusion (e.g. use draw_polyline for arcs/approximations), so it is clear context but not full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation profile is covered. The description adds genuinely new behavioral context: the operation is undoable with Ctrl+Z, and omitting layer falls back to the active layer. Those are real traits beyond the structured data.

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 purpose, then a when-to-use block, then parameters, then a concrete example — a clean, scannable structure. It is slightly label-dense and the example could be tighter, but no sentence is wasted.

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

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

Output schema exists, so return values need no explanation, and the description covers purpose, usage, parameter formats, layer preconditions and undo behavior. It does not state what happens if the named layer is missing, which is the only material 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 0%, so the description carries the full burden and does so: start/end accept [x, y] or [x, y, z] in drawing units, and layer must be an existing layer and is optional with a documented active-layer default. All three parameters gain meaning absent 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?

States a specific verb and resource ("Desenha uma linha no espaço modelo") and scopes it to axes, references and simple traces, which implicitly separates it from draw_polyline. The scope note does the work of differentiation without naming the sibling explicitly, so it falls just 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?

A dedicated "QUANDO USAR" line tells the agent when this tool fits (axes, references, simple geometry) and, by contrast, when a more complex primitive is warranted. It stops short of naming the alternative tools or stating exclusions outright, so a 4 rather than a 5.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=true; the description adds real behavioral detail by explaining that uniform Z produces a lightweight 2D polyline (with elevation) while varying Z produces a 3D polyline. It omits other operational traits such as whether a missing layer is auto-created and whether the drawing must be saved to persist.

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

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

Front-loaded with the core action and the Z-based rule, then a labeled usage block and a parameter list with an example. Every sentence is informative, though the parameter listing slightly overlaps with the schema.

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

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

With an output schema present, return values need no explanation, and the description covers behavior, usage, and all three parameters. Minor gaps remain around layer-existence handling and persistence requirements, but nothing essential 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 coverage is 0%, so the description must carry the burden and largely does: it documents points (≥2 points in [x,y] or [x,y,z] form), closed (fecha a figura), and layer, plus a concrete example. Only 'layer' lacks semantics about creation behavior or naming constraints.

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 ('Desenha uma polilinha por vértices') and adds the meaningful 2D-vs-3D branching rule based on Z uniformity, which distinguishes it from the sibling draw_line. It does not explicitly name the sibling it differs from, but the geometric distinction is clear enough for selection.

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

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

A dedicated 'QUANDO USAR' block gives concrete use cases (contornos, traçados de tubulação, perímetros), so the agent knows the intended context. It stops short of naming alternatives or exclusion conditions (e.g., when to prefer draw_line 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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation profile is covered; the description usefully adds that it produces real DIMENSION entities and defaults (dimstyle 'EZDXF'). It does not clarify whether the source DXF is modified in place or written to output_path, nor what happens to pre-existing dimensions.

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 purpose, then usage, parameters, kind schemas and an example in a scannable labeled layout with no filler sentences. The parameter block is dense but every line carries specific information, so it earns its length.

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

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

An output schema exists so return values need not be described; for a mutating, four-parameter tool with untyped nested objects the description covers invocation well. Missing pieces are sibling differentiation from 'add_dimension' and the write-target semantics of path/output_path.

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

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

With 0% schema description coverage the description carries the full burden and largely succeeds: it lists all four parameters, documents common nested fields (layer, color, dimstyle, text_height, arrow_size, decimals, lfac, text) and gives per-kind field shapes plus a worked example. It still leaves 'layout' and the in-place-vs-output_path behavior of 'output_path' unexplained.

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

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

The first sentence names a specific verb and resource (add dimensions to a DXF) and enumerates the supported kinds (linear, aligned, radius, diameter, angular) plus the fact it emits native DIMENSION entities. The only gap is differentiation from the near-identical sibling 'add_dimension', which the description never mentions or contrasts with.

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

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

An explicit 'QUANDO USAR' block gives concrete triggers (dimensioning spans, distances between supports, hole diameters), which is well above implied usage. However it offers no exclusions or guidance on when to prefer a sibling such as 'add_dimension' or 'draw_line'.

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, so the safety profile is covered. The description adds genuinely useful context beyond that: atomic all-or-nothing semantics ('Valida tudo antes de salvar: se uma entidade falhar, nada é gravado') and the layout default ('omita para o modelo'), which materially affect how the agent should call it.

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

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

Front-loaded with the purpose, then clearly partitioned into usage, parameters, field reference, and example. Dense but every section earns its place; no filler sentences.

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

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

For a 4-parameter mutation tool with an output schema (so return values need no explanation), the description covers purpose, atomicity, parameter roles, and per-entity structure. Minor gaps remain around path preconditions and what output_path does when set vs. omitted.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it largely does: it documents path, entities (list of objects with a 'type' key), layout (omit for model space), output_path, plus per-entity field shapes and a concrete example. It falls short of explaining output_path behavior (in-place vs. new file) or path format requirements.

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 ('Adiciona em lote entidades a um DXF') and enumerates all ten supported entity types, so the agent knows exactly what the tool produces. It only implicitly differentiates itself from single-entity siblings like draw_line/draw_circle via the 'em lote' (batch) framing rather than naming 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?

'QUANDO USAR: desenhar offline' is a terse, somewhat vague usage cue that doesn't name an alternative or state when NOT to use the tool. The batch framing implies the right context (multiple entities vs. the single-entity draw_* siblings), but the agent must infer that routing decision itself.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent ('sem alterar o arquivo'). Beyond the annotations it discloses the reporting behavior (flags errors and fixable items) and the fact that the check mirrors AutoCAD's own open-time validation, which is genuinely useful context about what the audit produces.

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

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

Front-loads the purpose, then a clearly labeled usage block, then parameter+example. Four short lines, no filler; every sentence carries distinct information.

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

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

With an output schema present, the description need not explain return values, and it covers purpose, trigger, and invocation. It is nearly complete; the only shortfall is that the single parameter is documented more thinly than the schema's 0% coverage warrants.

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

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

Schema coverage is 0% for the single 'path' parameter, and the description only labels it ('Parâmetros: path') and supplies an example (path="entrega.dxf"). The example implies a file path string, which is mildly helpful, but no constraints, format, or relative-vs-absolute guidance are given, so it only partially compensates for the empty schema.

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

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

States a specific verb+resource ('Audita a estrutura do DXF') and names the exact failure class it detects (erros que o AutoCAD acusaria ao abrir), which distinguishes it from diagnostic siblings like dxf_info or dxf_query. The non-modifying scope ('sem alterar o arquivo') further sharpens what the tool is.

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?

An explicit 'QUANDO USAR' block tells the agent the trigger situation (before publishing/delivering a DXF, whether generated or received). This is the clearest form of when-to-use guidance: a concrete workflow moment, not an implied context.

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

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

Annotations carry the safety profile (readOnlyHint=false, destructiveHint=true), so the bar is lower. The description still adds real context beyond annotations: it creates an empty file with default dimension/linetype styles, works offline, and notes overwrite defaults to false, which clarifies the write/destructive nature.

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 purpose sentence followed by labeled WHEN-TO-USE, Parameters, and Example sections. Every line earns its place with no 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?

An output schema exists so return values need no explanation. Purpose, trigger, full parameter semantics, and a usage example together give an agent everything needed to call the tool correctly.

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

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

Schema coverage is 0%, so the description must compensate and it does: it lists all four params and supplies the enum-like values (mm, cm, m, in, ft), the version range (R2000..R2018), the .dxf extension for path, and the overwrite default. This adds substantial meaning the schema lacks.

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 ('Cria um DXF novo e vazio') with a distinguishing scope qualifier ('sem abrir o AutoCAD') and notes the default styles included. It slots itself into the flow by naming dxf_add_entities as the fill step, so an agent can separate it from other creation 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 'QUANDO USAR' block gives an explicit trigger (start an offline drawing such as a support schematic or detail sheet) and names the follow-up tool dxf_add_entities. Clear context, though it offers no when-not-to-use or contrasting alternative for online/AutoCAD scenarios.

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 the safety profile (readOnlyHint=false, destructiveHint=true), and the description adds real context beyond them: '(ou confirma)' signals idempotent ensure-semantics, and output_path 'salva cópia, preserva o original' discloses that a copy can be written preserving the source (implying in-place mutation otherwise). The destructive nature itself is left to 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?

Well-structured with labelled sections (purpose, QUANDO USAR, Parâmetros, Exemplo) and front-loaded purpose. Every line earns its place; the example is genuinely useful. Minor redundancy in restating the tool name in the example.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety profile. The description supplies purpose, usage timing, param meanings, and a call example, making it usable as-is. It could yet clarify required-vs-optional params and destructive in-place behavior.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it names all five parameters and enriches them (color = ACI 1-255, linetype example 'DASHED', output_path semantics). It does not distinguish required (path, name) from optional/defaulted params, keeping it from a 5.

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

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

States a specific verb+resource: 'Cria (ou confirma) uma camada em um DXF.' An agent can immediately tell this creates/ensures a layer. However, it does not differentiate from the sibling create_layer, so sibling ambiguity remains.

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 'QUANDO USAR' line gives clear context: prepare layers (SUPORTES, COTAS, EIXOS) before drawing. This tells the agent the correct phase to invoke it. No explicit when-not-to-use or named alternative (e.g., create_layer) is given, so not a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the agent knows this mutates data. The description adds useful scope detail (viewports, paper, scale) but never explains why the operation is destructive, nor whether it modifies `path` in place versus writing to `output_path`, which matters for a destructive tool.

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

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

Front-loaded with purpose, then a clearly labeled QUANDO USAR line, a parameter line, and a concrete example. It is dense but every section earns its place; the long parameter line is slightly dense but justified at 0% schema coverage.

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 output-schema-bearing tool, return values need no explanation, and the description covers purpose, usage ordering, all parameters, and an example. The only real gap is the in-place vs output_path write behavior, which is not disambiguated.

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

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

Schema coverage is 0%, so the description carries the full burden and does so: it enumerates all seven parameters, gives the allowed paper values (A4–A0), and defines the nested viewport object fields (center, width, height, view_center, scale) including the non-obvious scale convention (0.01 = 1:100). The worked example reinforces the semantics.

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

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

States a specific verb and resource ("Cria um layout (folha) de papel num DXF") plus the scope of what the layout contains (viewports framing the model at scale). It is clearly distinguishable from siblings like dxf_create or dxf_export.

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?

"QUANDO USAR: montar a folha de impressão antes de dxf_export (PDF)" gives explicit ordering guidance and names the downstream sibling, which is exactly what an agent needs for sequencing. No when-not condition or exclusion is offered, so it falls short of a 5.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, so mutation is already known, but the description never says what gets destroyed or overwritten (e.g., an existing block of the same name) or how path vs output_path interact. It does add one useful behavioral constraint ('sem hatch/insert aninhado recomendado'), which slightly exceeds the annotation-only baseline.

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 purpose, then usage, params, and an example in clear labeled blocks. Slightly repetitive in re-listing parameters, but every section adds value and the example concretizes the entities/attributes format.

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

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

An output schema exists, so return values need not be explained, and the description covers usage, params, and a worked example for a fairly complex nested-entities tool. Remaining gaps are name-collision/overwrite behavior and the path vs output_path contract, which are not addressed despite the destructive hint.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does list all five params with meaning: entities 'mesmo formato de dxf_add_entities', attributes as a list of tags with an example, plus path/name/output_path. output_path is named but its difference from path is never explained, leaving one param under-specified.

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 um bloco... em um DXF') and clarifies the two-step flow by naming the follow-up insert operation. It does not, however, explicitly distinguish itself from the insert_block/list_block_definitions siblings beyond pointing at dxf_add_entities type=insert.

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

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

The 'QUANDO USAR' section gives explicit context with a concrete example (creating the SUP-GUIA support symbol with TAG/TIPO/LINHA offline). It provides clear when-to-use context but no exclusions or named alternatives for edge cases.

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, so the agent knows this is a write/destructive operation. The description adds real value beyond them: the hard 'confirm=true' requirement, that 'dry_run mostra a prévia sem gravar', and the ability to preserve the original via output_path. It doesn't state what happens if confirm is omitted (error vs no-op), so not a 5.

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

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

Front-loaded with the core action and constraint, followed by when-to-use, a parameter list, and a concrete example. It is appropriately sized, though the bare parameter enumeration is somewhat redundant with 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 destructive tool with a confirm gate, the description covers the safety mechanics and offers a working example, and the output schema can carry return-value detail. It is nearly complete, missing only handles-format detail and the failure mode when confirm is absent.

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

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

Schema description coverage is 0%, so the description carries the burden, and it partially compensates by explaining confirm (mandatory), dry_run (preview only), and output_path (preserve original). But 'path' and especially 'handles' receive no explanation of format or meaning, and the 'Parâmetros:' line merely restates the 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 names a specific verb+resource ('Apaga entidades de um DXF'), so an agent immediately knows this deletes entities. However, it never differentiates from the sibling 'delete_entities', which handles a very similar operation, leaving the agent to guess which one to pick.

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

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

'QUANDO USAR: remover entidades erradas' gives a clear usage context, and the note 'Prefira output_path para manter o original' prescribes a safer path. It stops short of naming exclusions or contrasting with the near-identical 'delete_entities' sibling.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, so the safety profile is partly covered, and the description adds genuinely useful behavior beyond that: the rendering is approximate and not identical to the AutoCAD plotter, and no AutoCAD installation is needed. It does not disclose that the target output file may be overwritten, which is the one mutation detail the destructiveHint warrants.

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 purpose followed by clearly labeled QUANDO USAR, Parâmetros, Exemplo and Observação blocks; every section is short and earns its place. The only minor redundancy is that output's allowed extensions appear both in the usage sentence and in the parameter 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 5-parameter tool the description covers the non-obvious arguments, gives a worked example, and flags the fidelity limitation; an output schema exists so return values need no explanation. The gaps are the ambiguity of `path` (disk file vs. active document) and the absence of any statement about overwriting an existing output file.

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

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

Schema description coverage is 0%, so the description must carry the load, and it largely does: it explains output extensions (.pdf/.png/.svg), layout semantics (omit for model), dpi bounds (30-600), and the meaning of background='white' vs 'default'. Only `path` is left undefined (filesystem path vs. a document already open in the session), which is why this is not a 5.

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

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

States a specific verb+resource (render DXF model or layout to PDF/PNG/SVG) and even names the engine (ezdxf + matplotlib) and the fact that AutoCAD is not required. It is clear what the tool does, but it never differentiates itself from the sibling plot_to_pdf, which appears to overlap on the PDF output case.

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?

'QUANDO USAR: gerar PDF de entrega ou imagem de pré-visualização' gives an explicit usage scenario and ties format selection to the `output` extension. There are no exclusions or named alternatives, and the obvious sibling plot_to_pdf is not addressed, so the agent must still infer which of the two export-style tools to pick.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the handle format convention but says nothing about behavior when the handle is missing/unknown, permissions, or performance on large drawings. With annotations carrying the safety profile, this is adequate but thin.

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 one-line purpose followed by a labeled usage block, parameter note and runnable example. No filler sentences; every line either routes the agent or pins a parameter format.

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 both required parameters plus their usage ordering are covered. The only gap is failure modes for invalid handles, which is minor for a read-only lookup.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: 'path' is named and 'handle' is qualified as hexadecimal with a concrete example ('2A3') plus a full call example. It stops short of 5 only because path's format/expected file location is not clarified.

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 ('Devolve os detalhes completos de uma entidade do DXF') and the lookup key ('pelo handle'). This distinguishes it from broader siblings like dxf_query, though it doesn't explicitly contrast with get_entity or dxf_read_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?

The 'QUANDO USAR' block gives explicit ordering guidance ('depois de dxf_query') and the intent ('ver geometria/atributos de uma entidade específica'), naming the sibling that precedes it. It lacks when-not conditions or alternatives among the create/query/modify siblings, so it stops short of 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful context beyond that: it operates without opening AutoCAD and reports a specific set of structural facts, though it doesn't discuss limits (e.g., very large files).

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

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

Front-loads the purpose, then layers WHEN-TO-USE, parameters, and a concrete example in labeled blocks. Every line earns its place and nothing is redundant.

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

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

An output schema exists, so return values needn't be detailed, and annotations cover the safety profile. Combined with the stated purpose, usage rule, parameter constraint, and runnable example, an agent has everything needed 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 0%, so the description must carry the parameter meaning, and it does: path is the .dxf path constrained to 'pastas permitidas'. The worked example reinforces the expected format. It stops short of specifying path syntax or behavior on invalid/out-of-scope paths.

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 ('Resume um DXF') and enumerates exactly what it reports (version, units, layers, layouts, blocks, dimension styles, extension), so an agent knows precisely what it returns. It also positions itself against siblings by being the entry point before any other dxf_* tool.

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 'QUANDO USAR' block gives a clear routing rule: use it first, before any other dxf_* tool, to confirm units and layer/layout names. It names the relevant alternative set implicitly but offers no explicit when-not-to-use case, keeping it short of a perfect 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write nature is covered. The description adds useful behavior (block auto-creation if absent) and a caveat that pictograms are simplified and non-normative, but says nothing about what a destructive write overwrites or how output_path differs from in-place editing.

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 purpose, then a usage block, parameter list, and a concrete example. The parameter list would be redundant against a described schema, but with 0% coverage it earns its place. Slightly long but no filler sentences.

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

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

An output schema exists, so return values need no explanation. For an eight-parameter destructive mutation tool, the description covers purpose, usage, all parameter names, and an example. The main gap is the semantics of output_path versus in-place modification, which matters for a write tool.

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

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

Schema coverage is 0%, so the description carries the load and does it well: it enumerates all eight parameters, supplies the kind values (GUIA, ANCORA, APOIO, MOLA) that the schema leaves as a free string, and explains size units/default and line meaning. Path, tag, layer and output_path are named but not elaborated.

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 ('Insere') and resource ('pictograma de suporte de tubulação'), enumerates the four kinds, and names the follow-up tool (dxf_read_attributes), so an agent can place it relative to siblings. No ambiguity about what is produced.

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 explicit 'QUANDO USAR' clause states the scenario (offline assembly of the support drawing/register) and notes the block SUP-<TIPO> is auto-created and later readable with dxf_read_attributes. Clear context, but no when-not or alternative-tool exclusions beyond the read counterpart.

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, so the safety profile is known. The description adds value beyond that by noting output_path is 'recommended: salva cópia', which implies edits otherwise happen in place on the source file, and by scoping attributes to blocks only. It still doesn't state reversibility or undo behavior, so a 4 rather than 5.

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

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

The text is front-loaded (purpose, then when-to-use, then a parameter digest, then a worked example) and each block earns its place. The example is genuinely useful for invocation. Minor redundancy between the parameter list and the example keeps it from a 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?

For a 10-parameter destructive mutation tool with an output schema and annotations available, the description covers purpose, usage context, per-parameter semantics, and an example. What's missing is an explicit statement of in-place/destructive behavior and sibling differentiation, but the essentials an agent needs to call it are present.

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

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

With 0% schema description coverage across 10 parameters, the description carries the burden and does so well: it gives formats/constraints for translate [dx,dy,dz], rotate_deg (+ rotate_center), scale (>0), attributes {"TAG":"S-01"} (blocks only), and flags output_path as recommended. Only color and layer semantics remain vague, so it is strong but not exhaustive.

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

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

The description gives a specific verb ('Altera entidades de um DXF') plus the resource and enumerates the modification kinds (layer, color, move, rotate, scale, block attributes), so an agent immediately grasps what it does. It stops short of explicitly distinguishing itself from similarly-scoped siblings like move_entity or update_block_attributes, so it does not reach a 5.

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

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

The 'QUANDO USAR' line supplies a concrete context (batch adjustments: changing support layers, shifting a segment, fixing a TAG), which is implied-to-clear usage guidance. However, it names no alternatives and does not tell the agent when to prefer this over single-purpose siblings such as move_entity or update_block_attributes, leaving the batch-vs-single distinction to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds real behavioral detail beyond that: pagination via offset/limit with a max of 500, wildcard support in layer/block, and that omitting layout targets the model space.

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 purpose sentence, then clearly labeled QUANDO USAR, Parâmetros and Exemplo sections. The worked example collapses several parameter semantics into one line, so every element earns its place.

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

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

An output schema exists, so return values need not be described. With parameters, filters, pagination and safety all addressed, the definition is largely complete; only the sibling disambiguation from query_entities 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 0%, so the description carries the full burden, and it largely succeeds: it enumerates all seven parameters with meaning, gives concrete type values (LINE, CIRCLE, INSERT...), notes wildcards on layer/block, and explains layout omission. The limit default (50) is not stated, only the max.

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 (lista) and resource (entidades de um DXF) plus scope (filtros e paginação, curingas). Clear what it does, but it does not distinguish itself from the similar sibling query_entities, so an agent must infer the split.

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?

An explicit 'QUANDO USAR' section tells the agent the intended context (inspect or count DXF entities without AutoCAD) and the pagination approach. It gives positive context but names no alternatives or exclusions, so the overlap with query_entities/dxf_sql_query is unresolved.

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

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

Annotations already cover the safe-read profile (readOnlyHint=true, destructiveHint=false), and the description adds genuinely new behavior: no AutoCAD dependency required and a hard refusal above 2000 blocks with the mitigation ('restrinja o filtro'). That limit disclosure is exactly the kind of extra context annotations cannot 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?

Front-loaded purpose, then grouped WHEN-TO-USE, parameters, and a runnable example — scannable structure with little waste. The parameter line is slightly terse relative to the example, but nothing is filler.

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

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

An output schema exists, so return shape need not be explained, and the description covers the guard-rail (2000-block cap) plus the usage scenario. The only shortfall is thin coverage of layer_filter 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 coverage is 0%, so the description carries the burden. It names all three parameters and gives a wildcard example for block_filter ('SUP-*'), but layer_filter gets no explanation and accepted filter syntax/value forms are only implied by one example.

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 ('Lê os atributos de blocos ... direto do DXF') and adds the useful differentiator 'sem AutoCAD'. It does not, however, distinguish itself from the sibling read_block_attributes (or dxf_get_entity), which a scanning agent would want resolved.

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?

A dedicated 'QUANDO USAR' block gives concrete scenarios (extract the support registry from an exported DXF, prepare offline spreadsheet/audit). It provides clear context but names no alternative tool, so the choice against read_block_attributes is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful constraints: SQL is SELECT-only and limit is capped at 1000, plus it is an in-memory index over entities/attributes. It does not cover error behavior or auth, but adds meaningful behavioral context beyond 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-loads the core purpose, then uses clear sections for usage, parameters, and an example. Every sentence earns its place, and the example directly illustrates a valid aggregated query. No wasted text.

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

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

An output schema exists, so return values need not be explained. The description covers when to use it, all parameters, allowed SQL columns, and a concrete example. Minor gaps like default limit behavior or path validation are 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 description coverage is 0%, so the description must carry parameter meaning. It lists all three parameters and explains the sql parameter's allowed columns for entities and attributes, plus the limit maximum. Path is not elaborated, but it is self-evident; this compensates well for the schema gap.

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

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

States a specific verb+resource: 'Consulta o DXF com SQL SELECT sobre um índice em memória (tabelas entities e attributes)'. This distinguishes it from generic siblings like dxf_query or query_entities by specifying SQL SELECT and the exact tables. An agent can tell what the tool does without opening the schema.

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

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

Includes an explicit 'QUANDO USAR' section for aggregated questions (counts by layer, blocks without TAG, total length by layer) with examples. It does not name alternatives or when not to use it, but the positive context is clear enough to route correctly.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true; the description adds that it only reads the drawing, that overwriting an existing file requires confirm=true, and that the workbook contains an INFO sheet carrying the drawing unit. The one residual gap is that it does not say what happens to the confirm=false default beyond the overwrite case, but the destructive surface is otherwise well disclosed.

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

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

Front-loaded with the output contract, then a labelled WHEN-TO-USE block, a parameter list, and one concrete example call. Every section earns its place, though the capitalized section header and inline param enumeration make it slightly denser than strictly necessary.

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; the description instead covers the column contract, the file-write/overwrite semantics, unit context, and a worked example. For a 5-parameter export tool, an agent has everything needed 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 0%, so the description carries the full burden and largely does so: block_name accepts wildcards * and ?, path must be .xlsx on the user's machine, layer is optional, confirm governs overwrite, and coordinates are in drawing units. sheet_name is only named without explaining its effect, which keeps this short of a 5.

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

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

States a specific verb and resource ('Exporta blocos para .xlsx') and enumerates the exact columns produced (HANDLE, BLOCO, CAMADA, X, Y, Z, ROTACAO, ESCALA_X/Y/Z + one column per TAG). It also distinguishes itself from the sibling round-trip tools by naming import_blocks_from_excel and sync_attributes_from_excel as consumers of the output.

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?

A dedicated 'QUANDO USAR' block gives explicit triggers: produce the support list/table of the drawing, or obtain a template spreadsheet to edit and reimport. It names the alternative tools it pairs with, so the agent knows why it would pick this over a generic export such as dxf_export.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the set of returned properties, which is largely redundant given an output schema exists, and says nothing about failure behavior for an unknown handle. Adequate but thin against an already-covered safety 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?

Three short lines, front-loaded with the purpose, then a labeled when-to-use block, then parameter format and example. Every sentence earns its place with no filler.

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

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

For a single-parameter, read-only getter with an output schema and safety annotations, this is nearly complete: purpose, sequencing, and parameter format are all present. Only error/not-found behavior is unaddressed, which is a minor gap.

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

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

Schema coverage is 0%, so the description must carry the burden, and it does: it specifies the handle is a hexadecimal string and gives a concrete example ("2F1A"). That is meaningful added semantics beyond the bare 'handle' property title.

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 resource and scope: full properties of ONE entity retrieved by handle, and enumerates the returned aspects (geometry, color, linetype, block attributes). The emphasis on 'UMA entidade' cleanly separates it from the plural query_entities 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?

The 'QUANDO USAR' section explicitly names the alternative tools (query_entities/read_block_attributes) and the condition under which this tool is chosen: inspecting one specific item after a broader query. Nothing is left to inference.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds substantial behavior beyond that: full-batch undoability via one Ctrl+Z, dry-run reporting of insert/update/error per row without touching the drawing, the confirm requirement for updates, per-row errors not aborting the batch, and blank cells being ignored rather than clearing existing attributes. That is rich, non-redundant behavioral context for a destructive write tool.

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

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

Front-loaded with purpose and then organized by the QUANDO USAR heading, the safe-flow sequence, and a parameter rundown; the inline example call is useful. It is a dense wall of text with no line breaks or sub-headings and some parameter prose could be trimmed, so it is efficient but not maximally scannable.

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-format detail is unnecessary, and annotations already cover the safety profile. The description closes the remaining gaps that matter for a destructive 11-parameter importer — confirmation gate, dry-run semantics, per-row failure handling, blank-cell behavior — leaving nothing material an agent must infer before calling it.

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

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

With 0% schema description coverage and 11 parameters, the description carries the full semantic load and does so: it documents path/sheet/header_row, enumerates the legal mapping targets (x,y,z,rotation(graus),scale,scale_x/y/z,layer,block,handle,ignore,"attr:TAG") plus auto-detection fallbacks, and explains block_name, key_tag (the update-vs-duplicate rule), layer, update_position, create_missing_layer, dry_run and confirm. This is meaning the schema alone does not provide.

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 precise verb+resource+scope: inserts or updates blocks row-by-row from an .xlsx spreadsheet, and adds the distinguishing trait that a single Ctrl+Z undoes the whole batch. This separates it cleanly from siblings like export_blocks_to_excel, sync_attributes_from_excel, and insert_block without opening any schema.

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

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

Explicit 'QUANDO USAR' section names the concrete use case (loading a support/TAG table into the drawing) and prescribes a safe flow: dry_run=true first, then execute. It also states the conditional gate — inserts need no confirmation, but any row that UPDATES an existing block requires confirm=true — which is exactly the when/when-not guidance an agent needs.

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, so the mutation profile is covered. The description usefully adds that a missing attribute TAG produces a warning and that the action is reversible via Ctrl+Z, plus that the block must already be defined. It does not describe return content, but an output schema exists.

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

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

Front-loads the core action, then sections for when-to-use and parameters; every line is useful. The example is somewhat lengthy but demonstrative, so it largely earns its place.

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

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

With an output schema available, return values need not be explained, and the description fully covers purpose, placement, required vs optional parameters with formats, unit conventions, error/warning behavior, and the alternative tool. 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 description coverage is 0%, so the description must carry the load, and it does: name (existing block, see list_block_definitions), point (2D or 3D in drawing units), scale (scalar or triple), rotation (degrees, counterclockwise), layer (must exist unless create_missing_layer=true), and attributes ({TAG: value}) with warning behavior. A concrete call example seals the mapping.

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

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

States a precise verb and resource ('Insere UMA referência de bloco') and narrows scope with 'UMA' (single reference from an existing definition). This clearly distinguishes it from bulk siblings like import_blocks_from_excel and from definition-creation tools like dxf_define_block.

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 'QUANDO USAR' section gives the exact condition ('colocar um suporte/símbolo em coordenadas conhecidas') and names the alternative plus its trigger ('Para muitos blocos a partir de planilha, use import_blocks_from_excel'). It also flags that the operation is undoable with Ctrl+Z.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds non-obvious behavior: count_instances is slower because it scans model-space references, and attribute tags are only read for the requested page. That pagination/perf disclosure is real value beyond the annotations, though it doesn't address permission or empty-result behavior.

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

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

Front-loads the purpose, then a labeled QUANDO USAR block, then a compact parameter list, then a callable example. Every sentence earns its place and the scoping critical for correct invocation (pagination affecting tag reads) is surfaced early enough to matter.

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

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

For a read-only listing tool with an output schema already covering return shape, the description supplies the usage precondition, the parameter semantics, perf caveats, and an example. Nothing essential for correct invocation is missing.

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

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

With schema description coverage at 0%, the description carries the burden and mostly succeeds: it defines name_filter syntax (* and ? wildcards with an example), explains count_instances and the limit/offset pagination interplay. include_xrefs is merely named with no meaning attached, so one of five parameters remains opaque.

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

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

States a specific verb and resource plus the exact payload returned: the drawing's block definitions and the attribute TAGS of each. This distinguishes it from read_block_attributes (which acts on instances) and from dxf_define_block (which creates definitions). An agent knows what it gets 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 QUANDO USAR section names a concrete precondition (before insert_block, to learn valid names/tags) and a companion workflow (building spreadsheets). It routes the agent relative to a sibling but offers no explicit when-not-to-use or exclusion, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behaviorally relevant context beyond that: the returned fields including the saved? and active? flags, and the crucial rule that all other tools operate on the ACTIVE drawing. It does not cover pagination or ordering, but for a read-only list this is solid added value.

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 purpose, then a dedicated usage block, then a concrete example. Every sentence earns its place; the parenthetical field list and example are compact and informative.

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

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

An output schema exists, so return values need not be spelled out, yet the description still confirms the key fields and gives a worked example. For a zero-parameter, read-only list tool with annotations and an output schema, 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 tool takes zero parameters, so the baseline is 4. The description correctly presents it as a no-argument call (list_documents()) rather than implying hidden inputs.

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

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

States a specific verb+resource: 'Lista os desenhos abertos no AutoCAD' and enumerates the returned fields (nome, caminho, salvo?, ativo?). It is clearly distinguishable from sibling list_* tools (list_layers, list_block_definitions) by naming AutoCAD open drawings as the resource.

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?

An explicit 'QUANDO USAR' section names the alternative tool (set_active_document) and the exact condition that selects this one: multiple open drawings where the acting target is unknown. It also states the operating assumption that all tools act on the ACTIVE drawing, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true / destructiveHint=false, so safety is covered. The description adds real behavioral detail beyond that: wildcard matching semantics, that limit=0 means the server default, and that offset drives pagination. It does not say which document or layout the layers are read from, despite siblings like set_active_document and list_documents implying multiple documents.

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?

Tightly structured with a returned-fields line, a QUANDO USAR line, a parameters line, and an example — the most decision-relevant content (what it lists) comes first. No filler sentences.

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

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

With an output schema present, the description need not explain return values, and its parameter documentation is complete. The one gap is scope: it never states whether layers come from the active document only or across all documents, which matters given list_documents and set_active_document in the sibling set.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so well: it explains name_filter's wildcard syntax (* and ?) with a concrete example ("PIPE-*"), marks it optional, defines limit's 0 = server default, and identifies offset as pagination. It even supplies a full call example, list_layers(name_filter="SUP*", limit=20).

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 ("Lista as camadas do desenho") and enumerates the attributes returned (nome, cor/ACI, tipo de linha, ligada, congelada, bloqueada), which clearly separates it from layer-mutating siblings like create_layer or dxf_create_layer. It never explicitly names a sibling or a boundary case, so it falls short of the top mark.

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?

"QUANDO USAR" gives a concrete triggering context: inspecting layer structure before drawing, inserting blocks, or checking standards. It gives no when-not condition and does not name alternatives (e.g. check_layer_standard, query_entities), so routing among similar tools is still partly left to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation risk is covered structurally. The description adds genuinely new behavioral context: the operation is reversible via Ctrl+Z, and displacement units follow the drawing unit. 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?

Front-loaded with the operation, then use context, then parameters and a concrete example — all in four short lines with no padding. The "Parâmetros:" line partially echoes the schema and the example, a minor 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?

An output schema exists, so return values need not be described, and annotations plus the undo note cover the mutation profile. What is missing is side-effect scope — whether dependent geometry (dimensions, block references) is affected and which document/layer context applies.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains the displacement format ([dx, dy] or [dx, dy, dz]) and its unit, and the example pins handle as a string identifier ("2F1A"). "Handle" itself is only implicitly defined as coming from query_entities, leaving a small gap.

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

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

The description states a specific verb and resource — moving an entity by a displacement vector — and even names the unit semantics. It is clearly distinguishable from copy_entity at the verb level, though it never explicitly contrasts itself with other mutation siblings like dxf_modify_entities or copy_entity, 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?

"QUANDO USAR: reposicionar um item já localizado (query_entities)" gives a clear use context and points at the sibling used to obtain the handle prerequisite. It does not state when NOT to use it or name a direct alternative for repositioning, so no exclusion guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true; the description adds real side-effect context beyond them (BACKGROUNDPLOT disabled during plot and restored afterward, layout plot configuration may change). It stops short of explaining how overwrite destroys an existing file, which is the main destructive risk the annotation flags.

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

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

Front-loads the core action, then structured WHEN-TO-USE, parameters, example and effects blocks. Every section earns its place; it is slightly long but the example and effects lines are genuinely useful for a plotting tool.

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

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

For a 4-param mutation tool with annotations and an output schema present, the description covers purpose, routing, all parameters and side effects. Only the destructive overwrite consequence is left implicit, which is a minor gap given the annotation and output schema coverage.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: path is a .pdf inside allowed folders, layout accepts a name or "Model" and is omitted for the active layout, plot_extents distinguishes fit-to-extents from saved config, overwrite defaults false. It adds the meaning the bare schema lacks.

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: plots the open drawing to PDF using AutoCAD's real "DWG To PDF.pc3" plotter. It also explicitly separates itself from the sibling dxf_export ("para PDF sem AutoCAD use dxf_export"), 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 "QUANDO USAR" block gives explicit when-to-use guidance (delivery PDF with PLOT fidelity) and names the alternative tool for the opposite case (PDF without AutoCAD → dxf_export). No inference required.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful behavioral detail that omitting key lists all keys, but says nothing about where the data lives if absent or what happens on a missing key; an output schema exists so return values are not its burden.

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 one-line purpose, then a labeled when-to-use, a parameter note, and a worked example. Nothing is bloated, though the example arguably restates information the parameter line already carries.

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-optional-parameter read tool with annotations covering safety and an output schema covering returns, the description supplies purpose, usage context, and parameter behavior. Only edge-case semantics (missing key, empty results) are unaddressed.

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

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

Schema coverage is 0%, so the description must compensate, and it does for the single parameter: key is described plus the default behavior (omit it to list all keys). The example reinforces this, though it does not state the key's casing/format conventions.

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 (Lê) and resource (dados de projeto gravados no DWG) and ties itself to the sibling that writes that data, project_data_set, so the read/write pair is inferable. It stops short of explicitly contrasting the two as alternatives, so it lands just under 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?

An explicit 'QUANDO USAR' line gives clear context: retrieving project metadata stored in the drawing. There are no exclusions or named alternatives for cases when this tool is the wrong choice (e.g., reading non-project DXF attributes), so it is clear context without 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 already declare the write/destructive profile; the description adds genuinely useful behavior beyond that — the data lives inside the DWG as an XRecord and survives save/reopen. It omits the consequence of setting a key that already exists (overwrite), which is the main thing the destructiveHint implies.

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 sections — the core behavior, the when-to-use trigger, and a worked example — with zero filler and the essential mechanics front-loaded. The example line is short and directly callable.

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 annotations cover the safety profile. Purpose, trigger, parameter limits and a usage example are all present, leaving only the minor overwrite-semantics 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?

With 0% schema description coverage, the description must carry parameter meaning, and it largely does: key length limit of 64 chars with no leading/trailing spaces, and value limited to 2000 characters of text. It stops short of stating key character restrictions or normalization rules, so the compensation is good but not complete.

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 ('Guarda um texto de projeto DENTRO do DWG') and even names the storage mechanism (XRecord dictionary 'AUTOCAD_MCP') plus its persistence across save/open. It does not, however, differentiate itself from the obvious sibling project_data_get, which is never mentioned.

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?

'QUANDO USAR' gives a concrete trigger with examples of the metadata to store (revisão, nº do documento, norma, responsável), so the agent knows when this tool applies. There is no explicit when-not and no pointer to project_data_get as the read counterpart, leaving the read/write pairing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavior beyond that: it returns a paginated summary rather than full properties, and documents that limit 0 means the default. It does not cover pagination edge cases or rate/scope limits, but for a read-only query it is solid.

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

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

Front-loaded with purpose, then clearly sectioned when-to-use, parameters, and a worked example. Dense but every sentence carries information; the trailing example is useful rather than filler.

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

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

An output schema exists, so return-value detail is not required. Combined with complete parameter coverage, explicit usage guidance, and a sibling alternative, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so for all 7 parameters: type (DXF names, comma list, aliases like "block"/"polyline"), layer (wildcards * and ?), block_name (INSERT only, uses effective name so dynamic blocks match), bbox (format and coordinate unit), bbox_mode (window vs crossing semantics), and limit/offset (pagination, limit 0 = default). This is meaning well beyond the bare 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 ("Busca entidades"), the resource, the mechanism (SelectionSet + DXF codes), and the return shape ("resumo paginado"). It explicitly distinguishes itself from the sibling get_entity, which returns full properties, so an agent can pick the right tool without opening either schema.

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

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

The "QUANDO USAR" section gives concrete when-to-use examples (all lines on layer X, blocks of a type, texts in a region) and names the alternative, get_entity(handle), with the condition that selects it. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. Beyond that the description discloses the returned attribute structure (TAG → value), wildcard matching behavior, and the pagination default — genuine context, though nothing about auth or result size limits.

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

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

Front-loads the one-line purpose, then layers QUANDO USAR, parameter notes, and a concrete example. Every block earns its place and the example is compact; the formatting is slightly list-like but readable and non-redundant.

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

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

Output schema exists, so return-value mechanics need not be restated, and annotations cover the safety profile. Given 0% schema description coverage on 4 optional params, the description supplies the missing parameter semantics, usage triggers, and an example — nothing an agent needs to call this correctly is absent.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it largely does: wildcards for block_name and layer, empty block_name = all blocks, and limit/offset pagination with 0 = server default. A worked example further anchors usage; only the offset semantics could be spelled out more precisely.

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 ('Lê referências de bloco') and enumerates what is returned (handle, posição, camada, dicionário TAG → valor). An agent can distinguish this from sibling mutators like update_block_attributes, though it never explicitly names a sibling reader such as dxf_read_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?

The 'QUANDO USAR' block gives concrete triggers: reading the drawing's support table, checking TAGs, or reading before updating values. No explicit when-not or named alternative, but the 'before updating' cue implicitly routes to update_block_attributes.

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 beyond the annotations: it discloses that SendCommand is asynchronous and returns nothing, prescribes the SETVAR USERS1 workaround for reading values, notes it is excluded from the server's undo grouping, lists expression constraints (single line, ≤2000 chars, balanced parens), warns that file/registry/process functions are blocked as only a partial defense rather than a sandbox, and states every execution is logged. For a destructive=true tool this is exactly the context an agent needs before calling it.

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

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

Front-loaded with the one-line what, then headed blocks for when-to-use and limitations, which makes it skimmable despite high density. It is long, but for a destructive, non-sandboxed eval tool nearly every clause earns its place; only the parameter list is compressed into an unhelpful run-on.

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 preempts the key surprise by saying SendCommand does not return the LISP result. Combined with the safety caveats, the logging note, and the workaround for reading values, an agent has everything required to call this tool safely and interpret its behavior.

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

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

Schema coverage is 0%, so the description must carry the load, and it does explain all three parameters (expression, confirm, wait_seconds with its ≤30s idle-wait meaning) plus the confirm=true requirement. The treatment of individual params is terse (a bare comma list) relative to the detailed expression constraints, so it falls just short of fully compensating.

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 ("Executa UMA expressão AutoLISP no AutoCAD via SendCommand") and explicitly positions itself against the rest of the toolset ("só quando nenhuma outra ferramenta faz o serviço"). An agent can immediately tell this is the general-purpose escape hatch rather than one of the many dxf_*/draw_* 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 QUANDO USAR block gives an explicit selection rule (use only when no other tool covers the case) plus a concrete example (Plant 3D-specific command). It also states the hard precondition confirm=true, so the agent knows not just when but under what gate to invoke it.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds the concrete consequence (overwrites the current file), the gating requirement (confirm=true), the failure behavior without confirmation (ok=false with a preview), and a precondition refusal. That is meaningful detail beyond the structured fields.

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

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

Front-loads the destructive warning, then when-to-use, precondition, parameter note, and a concrete call example. All sections are functional, though the labeled blocks and example make it longer than strictly necessary for a one-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?

For a destructive single-parameter mutation with an output schema present, the definition covers the safety profile, trigger condition, precondition failure, and confirmation gating. An agent has everything needed to call it correctly without opening the schema.

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

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

The single 'confirm' parameter has 0% schema description coverage, so the description must carry it — and it does: it states the parameter is required in practice to proceed and what happens when it is absent (ok=false plus preview). It stops short of explaining the preview payload itself, though the output schema covers returns.

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 with scope qualifier: 'Salva o desenho ativo POR CIMA do arquivo atual' (saves the active drawing over the current file). The overwrite semantics and destructive nature immediately separate it from adjacent tools like dxf_export or plot_to_pdf.

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 'QUANDO USAR: só quando o usuário pediu para gravar' gives a clear trigger condition, and it names a refusal case (unnamed drawing, never saved) plus the remediation (use SAVEAS in AutoCAD). Nothing about when to invoke is left to inference.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, so the mutation profile is already carried structurally. The description adds useful context (it retargets subsequent tool calls and does not open files), but it never reconciles the 'destructive' annotation — a mere context switch reads as benign/reversible, so the agent gets no explanation of what is actually destructive or whether the change is reversible.

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

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

Four tight segments — purpose, when-to-use, parameter semantics, example — front-loaded and each earning its place. 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 one-parameter state-switch tool with an output schema present (so return values need not be documented) and full annotations, the description covers purpose, usage, and parameter format. Only the failure behavior for an unmatched name 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 0% and the single parameter has no schema description, so the description must compensate. It states the type (str), that the value may be a bare name or a full path, that matching is case-insensitive, and gives a concrete example — strong compensation, though it doesn't say what error occurs when no matching open drawing exists.

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 ('torna ativo') and resource (an already-open drawing identified by name or path), and explicitly distinguishes itself from openers ('Não abre arquivos novos'). An agent can differentiate it from siblings like list_documents, save_document, and dxf_create without opening any schema.

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

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

Contains an explicit 'QUANDO USAR' clause naming the exact scenario (to switch the target drawing of the other tools) plus a clear exclusion ('não abre arquivos novos'). This is textbook when-to-use guidance.

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

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

Annotations already cover the read-only/no-destruction profile, and the description reinforces it ("sem alterar entidades ou salvar arquivos"). It goes beyond annotations by disclosing a hard size cap ("recusa exceder o limite") and the return location (data.snapshot), which are useful behavioral facts 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?

Front-loaded with the one-line purpose, then cleanly segmented into QUANDO USAR, Parâmetros, Exemplo, and Retorna blocks. Some content is mildly redundant across sections, but each block earns its place and nothing is 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?

For a 5-param, read-only snapshot tool with an output schema and read-only annotations, the description supplies the triggering context, the required filter, parameter roles, an example, and the downstream consumers. An agent has everything needed to call it correctly without opening the schema.

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

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

Schema description coverage is 0%, so the description carries the param burden and largely succeeds: it names block_filter, layer_filter and the key_tag/type_tag/line_tag family, explains the tag params as configurable attribute names, and provides a concrete call example. Minor gap: it asserts an "explicit filter" requirement while the schema marks no parameters required (all defaults null), leaving a slight ambiguity.

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 (capture a complete/limited register of supports) and adds scope qualifiers (no entity mutation, no file saving). It also names the downstream consumers audit_support_register and compare_support_register, so an agent can tell it apart from those siblings immediately.

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

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

"QUANDO USAR: antes de revisar atributos ou comparar revisões" gives a clear triggering context and pairs it with a prerequisite (explicit block/layer filter). It points to the alternative tools it feeds but does not spell out when NOT to use it, so it stops short of full when/when-not routing.

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

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

Beyond the readOnlyHint annotation, the description discloses a concrete failure mode (ok=false with error.code="autocad_not_running") and a side-effect guarantee ("nunca inicia o AutoCAD sozinho"). This is exactly the extra behavioral context annotations do not provide.

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

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

Front-loaded with the diagnostic summary, then a clear QUANDO USAR block, then params and example. Dense but every line carries routing or behavioral information; nothing is wasted.

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

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

For a parameterless read tool with an output schema, this description covers the full agent decision path: what it inspects, when to call it, and what happens on failure. Nothing needed 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?

Zero parameters, so the baseline is 4. The description reinforces this with "Parâmetros: nenhum" and a usage example, leaving no ambiguity about how to invoke it.

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

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

Names a specific verb+resource (AutoCAD diagnostic) and enumerates exactly what it reports: connection state, version, active drawing, units, entity count, active command. This lets an agent distinguish it from siblings like list_documents or system_capabilities 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?

"QUANDO USAR" gives an explicit trigger: first call of a conversation and when suspecting a problem (connection error, "AutoCAD busy"). It states the condition clearly but does not name specific alternative tools or a when-not-to-use case, so it falls just short of 5.

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