propose_schematic_import

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

The description reinforces and extends the annotations: no writes, a revision_token is returned, unresolved footprints block with status=blocked and no token, and blocking footprints are named. The one weakness is that it mixes in the confirm_* output convention ("returns it as output_pcb (also pcb_path; the board you passed in is source_pcb)") inside this tool's own description, which risks an agent expecting output_pcb from a dry run that writes nothing.

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 dry-run purpose is front-loaded and no sentence is pure filler, but it is delivered as one dense unbroken paragraph that folds in sibling confirm/verify semantics. The revision/output_pcb sentence is about other tools and dilutes an otherwise tight core.

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?

There is no output schema, and the description does cover the return contract (listed footprints and nets, staging locations, revision_token, blocked status) and the failure mode. Completeness is only dinged by the unexplained columns/spacing/output_dir parameters and the ambiguous statement about output_pcb.

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 only covers two of six parameters: schematic_path (defaults to the board's own .kicad_sch) and staging_origin ([x, y] page mm, default right of the Edge.Cuts box). The staging-grid parameters columns and spacing, plus output_dir and pcb_path, are never mentioned, leaving genuinely ambiguous knobs undocumented.

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 operation in plain terms ("Dry run of importing footprints and nets from the project's schematic into the board") and immediately defines the scope boundary ("writes nothing"). It also implicitly distinguishes itself from the confirm_* siblings by being the non-writing proposal half of the pair.

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 ordering is given for the whole workflow ("import_from_schematic -> board_outline -> board_rules -> ..."), and it names the clarifying sibling constraint ("Staged footprints are not placed: placement is a separate step"). It also states that both gates are stale until verify_board runs, which tells the agent when this result is authoritative.

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