propose_board_outline

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

The description adds substantial behavior beyond the annotations: it reports replaced items, footprints outside the outline without moving them, and holes touching existing items; it refuses overlapping keepouts unless allow_overlap is true; and it explains that it writes nothing while returning a revision_token. This is consistent with readOnlyHint=true, idempotentHint=true, and destructiveHint=false.

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 key point, dry run and writes nothing, is front-loaded, and the dense detail is mostly justified by the complex nested parameters and lack of schema descriptions. Some material about confirm behavior and full project ordering is broader than this single tool, but it remains useful context rather than filler.

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 nested-parameter tool with no output schema, the description is complete enough to call it correctly: it defines the dry-run behavior, input shapes, overlap gate, returned revision_token, output_pcb/pcb_path/source_pcb distinction, and the need for verify_board before gates are valid. These details compensate for the absent output schema and sparse input schema.

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?

With 0% schema description coverage, the description carries the burden and explains the important nested fields: outline {x, y, width, height, corner_radius?}, mounting_holes entries, origin enum meanings, and allow_overlap behavior. It leaves output_dir and perhaps pcb_path relatively implicit, so it is strong but not exhaustive.

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 description states a specific verb and resource: a dry run of replacing the board outline and adding mounting holes, including what would be replaced and what would be refused. It distinguishes itself from the confirm sibling by explicitly saying it writes nothing, returns a revision_token, and that confirmations write a new revision.

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?

It clearly establishes the dry-run use case, gives a project-order context, and warns that allow_overlap should only be set after a human has read the listed items. It also points agents to verify_board for certification. It does not explicitly name confirm_board_outline as the next step, so the alternative routing is implied rather than stated.

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