design_preview_plan

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

With no annotations, the description carries the full burden and does so: it discloses the hidden side effect that symbol extraction still consults Altium on cache miss (reads SchLib), that no project is created and nothing is placed, that an SVG file is written, and it lists the return dict keys (ok / preview_svg_path / canvas / counts / notes / failures).

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 behavioral contrast is front-loaded in the first sentence, and the Args/Returns structure is scannable. It is slightly long for a three-parameter tool, with some restatement between the prose and the Args block, but every section still carries usable information.

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

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

Covers pipeline differences, side effects, parameter formats, and iteration workflow; an output schema exists so the return-value enumeration is redundant but harmless. Minor gaps remain, such as whether the output directory must exist or whether an existing SVG is overwritten, but nothing blocking 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 compensate, and it documents all three parameters: plan_json accepts a JSON string or dict, output_svg_path has a stated default of <repo>/.symbol_cache/preview.svg, and placement_hints is explained structurally ({refdes: {x, y, rotation}}) with semantics of hinted-vs-algorithmic placement.

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 (render a DesignPlan to SVG) and immediately scopes it against the sibling pipeline: 'Same pipeline as design_execute_plan(use_canvas=True) minus the place + wire + save IPC pass.' An agent can distinguish this preview tool from design_execute_plan without inspecting either schema.

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

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

'Use this to sanity-check a layout cheaply before committing to a full emit' gives an explicit when-to-use, and the exclusion (full emit via design_execute_plan) is named. It even prescribes a workflow loop: 'Iterate preview→hints→preview to refine a layout before a full emit.'

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