Kicad Export

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

With no annotations, the description carries the full behavioral burden and does disclose real side effects: gerbers/drill write files into outdir, other targets write <stem><ext> into outdir, and pcb svg is forced to --mode-single --fit-page-to-board --exclude-drawing-sheet. It stops short of stating failure modes, permission needs, or whether existing output files are overwritten.

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 file-type-to-target mapping before the optional flag details. Dense and mostly every sentence earns its place, though the embedded CLI flag strings are slightly inside-baseball for an agent that only needs to pick a target.

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 the terse 'Returns the export command result' is acceptable. The gaps are minor: undocumented path/outdir defaults and no statement of what happens on invalid target/file-type combinations, which matters given the target list is conditional.

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 largely does: layers is explained as an optional comma-separated list with an example and a stated default for gerbers, and outdir's directory-vs-stem semantics are spelled out per target. path is only implicitly characterized (the input file whose extension selects the target) and outdir's empty-string default is never explained.

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 (export) and resource (KiCad file via kicad-cli), then enumerates exactly which targets apply to .kicad_sch versus .kicad_pcb. This is far more discriminating than any sibling (kicad_drc, kicad_erc, kicad_version), so an agent can route to it without ambiguity.

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

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

Gives clear context: the valid target set is conditioned on the input file extension, which is exactly the decision an agent must make. It does not, however, name when not to use it or point at alternatives (e.g., kicad_drc/kicad_erc for validation rather than export).

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