pcb_generate

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

With no annotations provided, the description carries the full burden and handles it well. It discloses network fetching from EasyEDA, 12-second rate-limit pauses, SQLite caching, auto-placement behavior, wire generation, board outline drawing, and output as a file. It does not mention overwrite behavior or failure modes, but the main side effects are transparent.

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?

Six information-dense sentences with the core purpose front-loaded and supporting details about latency, caching, placement, and requirements following. Every sentence earns its place, though a few details are partially redundant with the input schema descriptions.

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 complex tool with 5 parameters, a nested spec, and no output schema, the description is quite complete: it explains the output, external dependencies, performance characteristics, and system prerequisites. It defers the full spec schema to plugin docs and does not specify whether an existing output file is overwritten, but an agent has enough context to call this 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 100%, so the baseline is 3, but the description adds real semantic value beyond the schema. It explains that components need an LCSC C-number, that nets can reference pin names rather than pin numbers, and that pin maps are cached and can be bypassed. This meaningfully enriches the spec parameter and the fetch-related flags.

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 action ('Generate a fully-wired .kicad_pcb') from a declarative spec and names the mechanism (pcbnew API). It clearly names the output artifact and distinguishes itself from schematic-oriented siblings by describing PCB-specific behaviors such as auto-placement, pad-to-pad wiring, and board outline drawing.

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 provides clear context: use this when you have a declarative spec with LCSC C-numbers and need a ready-to-route PCB file. It also states the hard prerequisite of KiCad 8+ being installed. It does not explicitly name alternatives or say 'use sch_generate for schematics instead,' 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.