propose_pour_step

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely new behavior: writes nothing, runs no router, returns a revision_token, skips nets that already have a pour on that layer, and explicitly yields no verdict (only verify_board does). The skip-existing behavior and the 'no verdict' caveat are facts the annotations cannot convey; only the exact return shape of revision_token remains unstated.

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 dry-run contract, then parameters, then sequencing, then the caveat — a sensible order with no filler. It is slightly dense in a single run-on paragraph with the pours example inlined, which costs a bit of scannability but nothing is wasted.

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 three-parameter, sequenced dry-run tool with no output schema, the description covers prerequisites, side effects, the nested parameter format, output directory constraints, and what the tool will not do. The only gap is what the revision_token looks like and what validation failure reports, which the agent cannot infer.

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 carry the parameters. It fully specifies the nested 'pours' map with type (net name → copper layer), a one-net-per-layer constraint, and a concrete example, plus output_dir semantics (new directory, default sibling `<project>_poured`, must not be inside the source project). pcb_path is not described, keeping this short of a 5.

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?

Opens with a specific verb+resource ('Dry run of the pour step') and states exactly what happens: validates power planes, returns a revision_token, writes nothing. It also names the sibling that provides the real verdict (verify_board) and implicitly contrasts with confirm_pour_step, so the agent can distinguish it from the rest of the propose/confirm pairs.

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 an explicit prerequisite chain (propose/confirm_input_preparation, then pin_rule_baseline, then this step) and a cardinality rule ('once, before routing signals'). It also explains why the ordering exists ('copper-layer text is refused by confirm'), which is exactly the when-to-use context an agent needs.

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