autocad_set_drawing_units

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the 'safe to call repeatedly' line is largely reinforcing structured data. The genuinely additive disclosure is that rejected variables are surfaced in the 'verified'/'warnings' payload rather than silently dropped or thrown as errors, which tells the agent to inspect the result rather than assume full success.

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

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

Purpose is front-loaded in the first sentence, followed by grouped defaults, idempotency, Args and Returns sections. Well organized and reasonably sized, though the default template is restated in both the description and the nested schema's own description, which is mild 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?

For a one-parameter configuration call, the definition covers purpose, default behavior, idempotency, a field inventory, the exact return shape, and explicit guidance on verifying partial success. Combined with annotations that carry the safety profile, nothing an agent needs to invoke or interpret it 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 measured schema coverage is 0% at the top level (the single 'params' property is an undescribed $ref), but the nested $defs do document each field. The description compensates meaningfully by naming all seven sub-fields and, crucially, spelling out the default template values (Engineering length at 0.000, Decimal Degrees, counter-clockwise, Inches, International) so an agent knows the effect of omitting 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 and resource ('Apply the Drawing Units dialog settings') plus an extra outcome ('verify each was accepted'). No sibling tool in the list touches drawing units, so this is unambiguously distinguishable from the layer/entity/dimension tools.

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

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

The description implies when to call (to configure drawing units) and tells the agent what happens by default (Engineering template) and that repeated calls are a no-op. However, it never states when in a workflow to invoke it, whether it must precede drawing creation, or any when-not condition.

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