Koppar

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

Annotations only declare the generic safe-mutation profile; the description goes further by disclosing that no validation happens here ("Nothing is checked here"), that nets must already exist on the board, and how to undo via ripup_routing. It does not cover failure behavior for a missing net, but the net-existence precondition is a real, non-obvious constraint the annotations do not carry.

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?

Four short sentences, front-loaded with what gets created, then defaults, then preconditions, then caveats/follow-ups. No filler and no restatement of the name or title.

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 mutation tool with no output schema, the description covers purpose, defaults, preconditions, verification and reversal — enough to call it correctly. Minor gaps (batch limits of 500 vias / 200 tracks, error behavior on an unknown net) are covered by schema constraints or left implicit.

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 50% schema coverage, the description compensates where it matters most: width_mm, diameter_mm and drill_mm "default to the board's current track and via sizes," which is not inferable from the schema. wait_s and design_id are well documented in the schema itself, and the track/via shapes are described structurally.

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?

"Lay exact copper by hand ... tracks as polylines on one copper layer, and through vias" names a specific verb (lay copper) plus both resources (tracks, vias) and their shape. The phrase "where the routers leave a gap" cleanly separates it from route_board (automatic) and ripup_routing (removal), so an agent can pick it without opening a schema.

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 gives an explicit usage context (manual touch-up after the router) and names the follow-up and undo paths: run_drc afterwards, ripup_routing to remove copper. It stops short of an explicit exclusion such as "do not use for bulk routing — call route_board instead," so it is clear context rather than a full when/when-not rubric.

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

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

Annotations only declare the safety profile (not read-only, not destructive, closed-world); the description adds real behavioral context beyond them: the footprint joins the design's 'custom' library, is addressable as custom:<name>, is loaded by the board builder like a library footprint, and is carried into the KiCad project download. It does not cover overwrite/name-collision behavior.

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 purpose, then downstream usage, then constraints, then the CLI equivalent. Dense but essentially waste-free; the embedded CLI line is the only element that could be seen as optional.

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?

No output schema exists, and the description compensates by explaining where the artifact lands and how it is referenced later. Only minor gaps remain around failure modes and whether re-adding a same-named footprint overwrites.

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 baseline is 3, but the description adds genuine meaning: the resulting name maps to the 'custom:<name>' handle used downstream, and the kicad_mod content must have pads numbered like the pins — a constraint not present in the schema.

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+resource (add a KiCad .kicad_mod footprint to the design) and scopes it to 'a package KiCad's libraries lack', which implicitly separates it from search_kicad_footprint and get_kicad_symbol. An agent can tell exactly what artifact this produces and how it is identified (custom:<name>).

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: use it when KiCad's libraries lack the package, and then consume the result via create_custom_symbol(footprint=) or the SKiDL script's footprint=. It does not explicitly tell the agent to try search_kicad_footprint first, so it stops short of full when/when-not routing.

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

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

With annotations already declaring readOnlyHint=false, openWorldHint=false and destructiveHint=false, the description adds genuinely useful behavior: existing files are kept unless overwrite is true, the reply itemizes written/replaced/kept files, input is base64 and capped near 18 MB zipped. That overwrite path replaces existing files, which is worth stating given destructiveHint=false, but the description discloses it rather than contradicting the annotation.

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?

A single dense sentence pair, front-loaded with the action and followed by semantics. It is packed but every clause carries information; no filler or restatement of the title.

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 mutation tool with no output schema, the description covers the write semantics, the opt-in overwrite path, the response contents (written/replaced/kept), and the input size/encoding constraints. Only the absence of tie-ins to related import tools leaves a small gap.

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 only 33% (just design_id documented), but the description compensates for both undocumented parameters: it explains what overwrite=true does and clarifies the zip_base64 encoding and the ~18 MB zipped ceiling that corresponds to the 24,000,000-char base64 maxLength. That is real added meaning beyond the schema.

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 gives a specific verb and resource: 'Unpack a ZIP into the project folder, keeping its paths,' and enumerates what the ZIP may contain (footprints into a .pretty library, 3D models, a library table). An agent can tell this is a file-import operation on an existing project, though it never explicitly contrasts itself with siblings like import_kicad_project or add_custom_footprint.

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?

Usage is only implied by the content it handles ('new footprints into a .pretty library the fp-lib-table names, 3D models, a library table'), which suggests adding KiCad assets to an existing design. There is no explicit when-to-use statement, no prerequisites, and no named alternative such as import_kicad_project or add_custom_footprint.

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

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

Beyond the annotations (which only declare readOnlyHint=false and destructiveHint=false), the description discloses many behavioral details: it respects courtyard gaps, holds fixed/locked parts, keeps keepout rectangles clear, honors edge connector constraints, applies a per-pad price for bottom-side pads via flip_cost, starts from current positions unless from_scratch, runs at about a minute per 600k iterations, and recommends follow-up checks. This is rich context well beyond structured fields.

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 description is front-loaded with the core purpose and is appropriately sized for a complex placement operation. The sentences carry useful information, though the first sentence is long and dense; every part still earns its place.

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?

Given a tool with 30 parameters, no output schema, and only basic safety annotations, the description provides sufficient high-level context: what it optimizes, what constraints are honored, how it starts, and what to do afterwards. It does not cover job-status semantics (covered by the wait_s schema description) or every parameter, but it is broadly complete for an agent to invoke it 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 description coverage is 77%, which is high enough that the schema itself documents most parameters. The description adds some meaning for a few parameters (e.g., flip_cost as 'mm of wirelength', edge connectors held on their edge, fixed/locked parts held, keepouts kept clear), but it does not explain the majority of the 30 parameters. Baseline 3 is appropriate.

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 clearly states a specific verb and resource: 'Dense placement by simulated annealing'. It also distinguishes the tool from its sibling auto_place by noting it is 'slower than auto_place ... and much denser', so an agent can tell when this tool is the right choice.

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 for use: it is slower but much denser than auto_place, starts from current positions unless from_scratch, and advises to 'Check overlapping_pairs and run_drc afterwards'. It does not explicitly state when to avoid this tool or provide a full decision tree, but the alternative and trade-off are clear.

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

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

Annotations already declare a non-read-only, non-destructive, closed-world mutation, and the description adds real value on outcomes: nothing is left outside the outline except a 1.2 mm connector lip, and placement_notes reports every part that could not be placed as asked. It still does not disclose job/async behavior or what a placement actually changes, so it stops short of rich behavioral context.

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 engine, then a compact parenthetical constraint roll-up and the coarse-then-refine hand-off. Dense for 26 parameters but every clause is load-bearing; the nested edge/keepout parenthetical is slightly hard to scan.

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 26-parameter placer with no output schema, the description covers what the tool changes, what constraints bind it, and what it returns (placement_notes, the 1.2 mm lip exception). Gaps remain around placer vs refine selection and async job return behavior, which only the schema hints at.

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 81%, so the baseline is 3; the description earns above that by pinning semantics for the constraint families — fixed (exact origin and rotation, never moved), locked footprints, side, keepout rectangles, groups, near-with-maxMm, and edge syntax with optional '@mm' measured from the outline's top-left. It does not touch the refine-specific weights, which the schema covers anyway.

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 and resource ('pack footprints inside the board outline') and names the engine ('Koppar's heuristic placer, ratsnest-driven, courtyard-legal'). It explicitly positions itself as the coarse pass whose output should be refined with place_footprints, which distinguishes it from place_footprints and anneal_place.

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?

Explains the default selection behavior (all unlocked move, locked stay) and when refs overrides it, plus the 'coarse by design: refine with place_footprints' routing. It never explicitly excludes anneal_place or place_footprints from the initial-placement role, so the sibling boundary is only half-drawn.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, so the mutation profile is known; the description adds real value beyond that by disclosing the placement rules (well inside the island, inside the net's main copper on another layer, clear of every other net) and the partial-failure behavior ('Reports the islands it found no site for'). It does not mention that the work runs as a job, though the wait_s schema entry covers that.

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?

Three short sentences, front-loaded with the operation and followed by failure reporting and the next step; nothing is padding. The long appositive listing placement constraints is dense but each clause carries operationally relevant information.

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 destructive copper-modifying tool with no output schema, the description covers what is created and what is reported on failure, but leaves max_vias unexplained and does not state prerequisites (routing/fill must exist) or how net scoping affects the operation. Adequate but with clear gaps.

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 75% schema description coverage, the schema documents nets, wait_s and design_id, so a baseline of 3 applies. The description adds no parameter-level detail, and max_vias is undocumented in both schema and description ('one through-via per island' only loosely hints at a cap).

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 gives a concrete action and object: adding one through-via per island that KiCad finds cut off from its net. It is clearly distinguishable from siblings such as tie_rail_pads or polish_vias, though the opening clause ('A filled pour cut into islands by routing') is a strained sentence fragment that takes a second read.

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?

Usage context is implied ('a filled pour cut into islands by routing') and a post-step is prescribed ('Run run_drc afterwards'), but no sibling alternative is named and there is no explicit when-not guidance (e.g. versus fill_zones, repair_board, or diagnose_open_nets for open nets).

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

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

The description discloses the substantive behavior — what counts as a violation, the diff_pair_gap coupling criterion, the X_P/X_N, X+/X-, CAN X_H/X_L name patterns — which is real value beyond the annotations. However it is silent on side effects and statefulness, and annotations declare readOnlyHint=false, so an agent cannot tell whether a 'check' persists results or touches the board; that gap is not addressed.

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?

Two sentences, no filler, and the key differentiator (DRC doesn't check this) is front-loaded. The single long sentence is dense but every clause enumerates a distinct measured quantity that the agent would otherwise have to guess.

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, yet the description never says what comes back — a pass/fail list, per-net violation records, or a job handle beyond the wait_s case. It is strong on what is measured but leaves the result shape and any threshold/units to inference, which matters for a tool whose entire value is the report it produces.

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 100%, so design_id, the pattern constraint, and the wait_s/running-job follow-up with get_board_job are already fully documented in the schema. The description adds nothing about either parameter, so baseline 3 applies; 'the project's net classes' only loosely corroborates that design_id selects a design.

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?

Specific verb plus resource: checks copper against the project's net classes and differential pairs. It explicitly names the boundary against run_drc ('which KiCad's DRC does not') and enumerates the exact quantities measured (narrowest track, length below class width, coupled share at diff_pair_gap, skew), so an agent can distinguish it from run_drc and check_physics without opening a schema.

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?

'which KiCad's DRC does not' gives an implicit routing rule to this tool for class/diff-pair conformance, and 'Routing applies the same rules' implies it belongs after routing. But there is no explicit when-to-use, no statement of preconditions (routing finished? rules set via set_design_rules first?), and no mention of the sibling tools that fix these violations (widen_nets, couple_pairs, tidy_copper).

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

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

Annotations cover readOnly=false and destructive=false, and the description adds meaningful behavior: with repair, fixes are applied in place and each is kept only if KiCad counts nothing worse — a rollback/guard semantic the annotations cannot express. It omits the return/report format and whether the board must be routed/complete first.

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 purpose, and every clause carries substance (checks, conditional execution, repair behavior). It is dense and somewhat run-on as one long sentence plus a repair paragraph, 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 3-param check tool with no output schema, the description covers what is checked, when checks fire, and repair semantics. The main gap is the shape of the returned findings/report, though job-follow behavior is already documented in the wait_s schema field.

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 67%, with wait_s and design_id documented in-schema; the undocumented repair flag is the one the description explains best, detailing exactly what gets fixed (track width, skew meanders, return vias, widened rails) and the acceptance condition. It adds real meaning beyond the schema for the one gap.

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 and resource ('Judge the copper by physics') and then enumerates the exact checks performed: impedance from stackup, IR drop/heating, skew, ground-via at layer changes, 3W spacing, via path under paddles. It also positions itself against siblings by naming what KiCad's DRC does not catch and noting finish_board runs the same repairs.

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?

Explains the selection condition 'each check runs only when the board states something it can judge' and clarifies the repair branch versus finish_board, which runs the same repairs. It implies run_drc handles standard DRC but does not state an explicit when-not-to-use case.

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

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

Annotations already declare this is a non-read-only, non-destructive, open-world operation. Beyond them, the description discloses the key behavior that null reverts the line to the automatic pick and that the change is confined to sourcing, which is real context the annotations don't convey. It doesn't detail validation or error behavior, keeping it from a 5.

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?

Two dense sentences, front-loaded with the action and scope, with no wasted words. The null-revert and sourcing-only boundary are packed into the same compact block.

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 3-parameter mutation with full schema coverage, annotations, and no output schema, the description supplies the missing behavioral context (null semantics, sourcing scope) needed to call it correctly. Only minor gaps (validation/error outcomes) remain.

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 genuine meaning: it identifies `refs` as the line's references and explains that `part` must come from the offer or alternatives shown in get_bom, plus the null-revert semantics. This provenance guidance goes beyond the schema text.

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+resource ("Pick which offer a BOM line uses") and immediately scopes the input to references plus a seller part number or MPN. It distinguishes itself from siblings by naming get_bom as the option source and framing component changes as a different operation. An agent can tell it apart from get_bom and edit_circuit without opening a schema.

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 a clear when-to-use (choosing an offer for a BOM line), an alternative behavior (null returns to the automatic pick), and an exclusion ("Sourcing only: a different component is a circuit change"). It stops short of naming the specific sibling tool to use for a component change, but the boundary is unambiguous.

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

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

Goes well beyond the destructiveHint=true annotation: it discloses that zones are refilled first so pours count as connections, that locked items are preserved, that the board is rolled back if the unconnected count or DRC errors rise, and how overhangs are trimmed. The definition of 'contact' (copper overlap as KiCad judges it) is exactly the kind of domain-specific behavioral detail an agent cannot infer.

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 removal targets, then the safety and reporting behavior, with no filler sentences. Some parentheticals ('a free end, and everything the track touches stays joined without it') are dense but carry real meaning; nothing is redundant.

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 destructive 8-parameter mutation with no output schema and no annotations beyond safety hints, the description covers the critical gaps: what gets deleted, what is exempt (locked items), rollback conditions, and what list_removed reports. Only minor items are unaddressed, such as the default state of the category flags and the long-running job follow-up (partly handled by the wait_s schema text).

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 only 25%, so the description must compensate, and it largely does: it ties the three category booleans to their targets (duplicates, dangling/stub tracks, under-connected vias) and explains trim_overhangs, list_removed, and the implicit refill flag. It does not state that these are independent on/off selectors or their defaults, leaving some semantics to inference.

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 (sweep the routing) and enumerates exactly which items are removed: zero-length/duplicate tracks, stub tracks, and vias touching their net on fewer than two layers. This is precise enough to distinguish it from pruning/polishing tools, though no sibling is named to make the contrast explicit.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative, even though the sibling list contains obvious near-neighbors (prune_vias, polish_vias, tidy_copper, repair_board, ripup_routing). The text describes what the sweep does and how it behaves, not the conditions under which an agent should pick it over those tools.

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

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

Annotations mark it as a non-read-only, non-destructive mutation; the description usefully adds that each swap is persisted as the line's choice, that it is individually reversible via choose_bom_part with null, and that unmatchable lines are reported and left untouched rather than erroring. That failure and reversibility behavior is exactly the context annotations cannot express, though auth/permission needs are 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?

Three sentences, front-loaded with the core action and matching criteria, followed by motivation and edge-case handling. Dense but every sentence carries information; parenthetical asides are compact rather than wasteful.

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 two-parameter mutation with no output schema, the description covers matching rules, the fee rationale, reversibility, and unmatchable-line behavior, which is most of what an agent needs before calling it. Missing only expected result shape (e.g., count of swaps) which the absent output schema would otherwise carry.

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 both parameters (design_id, boards) are already documented in the schema, including the boards default and design_id format. The description's value-add is matching logic (same value, package, at least equal voltage for capacitors) rather than parameter meaning, so the baseline 3 applies.

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?

Names a precise verb (move/consolidate), the exact resource (resistors, capacitors and inductors), and the target library (JLCPCB basic). It is unmistakably distinct from siblings like choose_bom_part or get_bom, which handle individual selection or retrieval rather than bulk library substitution.

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 a clear rationale for when to use it (every off-library part adds a loading fee exceeding the part cost) and describes the scope limit (only R/C/L passives with readable value, SMD size and a basic equivalent). It also names the undo path (choose_bom_part with null). It stops short of an explicit 'do not use this if...' statement, so it's strong rather than exhaustive.

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

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

Goes well beyond destructiveHint=true by disclosing the exact mutation ('both legs are ripped and routed alone') and the full acceptance gate that decides whether the new copper is kept: coupling gain, skew limit, no new opens/DRC errors, and a via budget. That tells the agent both what can be destroyed and when the board is left untouched.

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 trigger and the ordering rule, then the acceptance criteria, then the sanity-check step. Dense but almost every clause carries information; the aphorism 'Pairs routed with the whole board lose their lanes; alone they couple' is evocative rather than precise and is the one soft spot.

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 12-parameter destructive routing operation with no output schema, the description covers trigger, mutation, keep/discard criteria, and follow-up verification, and wait_s in the schema routes the agent to get_board_job for long jobs. Minor gaps remain: bridge_islands and ml_options are unexplained and nothing says what the board looks like when no pair passes the gate.

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 83%, so the baseline is 3, and the prose adds real meaning for the gate parameters (min_gain_pct as coupling points, max_skew_mm as kept length mismatch, max_extra_vias as board-level via budget). However, bridge_islands and ml_options are undocumented in both schema and description, and tries/time_budget_s/total_budget_s get no prose treatment.

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 (re-route), resource (weakly coupled differential pairs), ordering rule (least coupled first) and prerequisite (after route_board). An agent can distinguish this from route_board and ripup_routing without opening any schema.

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 sequencing: 'After route_board' and 'Run check_net_rules before and after.' It also explains why this tool exists versus routing everything at once ('Pairs routed with the whole board lose their lanes; alone they couple') and scopes the work to pairs under target_pct.

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

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

Annotations only cover the safety profile (readOnlyHint=false, non-destructive, closed-world). The description adds substantial behavioral context: the part is registered as Part('custom','<name>'), added to the Verified parts table, the call is rejected without a footprint for 3+ pins, footprint_mod is validated as a KiCad footprint and stored as 'custom:<name>', and it propagates into project.zip and the fp-lib-table.

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 routing condition and the destructive alternative, which is the most decision-relevant content. It is dense and long, but nearly every sentence carries non-obvious constraint information. Minor tightening possible around the footprint_mod storage/pipeline details.

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 an 8-parameter, non-read-only tool with no output schema, the description supplies the pin-to-pad relationship rule, the validation/rejection behavior, and the downstream effects. An agent has everything needed to invoke it 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 75% and the description meaningfully supplements it: it explains the footprint requirement for 3+ pins, the footprint_mod vs footprint relationship ('footprint is then not needed'), the name sanitization to letters/digits/_ . + -, and the instruction to list every pad including NC pins. It does not cover datasheet, description, or reference, but these are self-explanatory.

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 (Register) and resource (connectable schematic symbol) plus an explicit scope constraint: parts NOT in KiCad's libraries. It clearly distinguishes itself from the sibling search_kicad_symbol / get_kicad_symbol tools by naming the failure condition that routes an agent here.

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?

Explicitly says when to use it (specialty ICs, when search_kicad_symbol returned nothing) and what NOT to do instead (telling the synthesizer to model the part with discrete passives, which 'breaks the board'). It also names the alternative path (footprint_mod vs footprint) with the condition that selects each.

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

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

Annotations already declare non-read-only, non-destructive, closed-world. The description adds genuinely new behavioral facts: no generation quota is consumed and the generation work is performed by the calling agent, plus downstream effects (design_id consumed by every other tool, web_url for the user). It stops short of describing failure modes or project-collision behavior, which live only in the schema.

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?

Two tight sentences; the action and its inputs come first, then the return values, then the quota note. No sentence is filler, and the quota remark earns its place by changing how the agent plans its work.

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 covers that gap by naming both return values (design_id, web_url). With four params and 100% schema coverage, the only unaddressed area is project/session behavior, which the schema itself documents adequately.

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. The description earns above that by expanding what belongs in 'brief' (interfaces, power, size, constraints) beyond the schema's terser 'user's terms plus anything you clarified', giving the agent concrete content guidance for the critical required parameter.

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 and resource ('Start a new design from the user's brief') and enumerates the brief's required dimensions, plus what it returns. It does not differentiate itself from the similarly-named sibling start_board, which is the main ambiguity an agent could hit.

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 phrase 'from the user's brief' and 'the work is done by you' imply this is the entry point the agent drives itself, but there is no explicit when-to-use / when-not-to-use statement and no named alternative (e.g., restore_design for existing work or start_board). The guidance 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.

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

Annotations already declare destructiveHint=true, but the description adds substance they do not carry: this is a reversible trash operation, it disappears from list_designs and the web app, and it is rejected mid-run. It also contrasts the irreversible permanent variant, which is exactly the risk context an agent needs before deleting.

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 destructive-versus-reversible distinction is front-loaded and each sentence adds information. The closing CLI mapping is tangential to an MCP invocation, but it is a single short line and does not obscure the core behavior.

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 two-parameter destructive tool with full schema coverage and no output schema, nothing material is missing: effect, reversibility, blocker, and recovery alternative are all covered. An agent can invoke it safely on the strength of the description alone.

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% and both parameters are documented there, so the schema already does most of the work. The only added meaning is that the target may be a board workspace as well as a design, which slightly widens the interpretation of design_id beyond the schema's 'returned by create_design or list_designs'. Baseline 3 is appropriate.

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 clause gives a specific verb and resource ('Move a design (or a board workspace) to the trash') and immediately scopes the effect ('it leaves list_designs and the web app'). It is clearly separable from restore_design and from a permanent removal, so an agent can choose it without opening a schema.

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 states when to use it (default soft delete), how to get the other behavior (permanent), the recovery path (restore_design), and the one blocking condition ('Refused while a run on it is in progress'). That is explicit when/when-not guidance plus named alternatives.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing the diagnostic model: corridor checks per layer, via-site feasibility, named blockers, CRAMPED detection with 'no router can reach it', and rip-and-retry advice. It does not mention that long runs return a 'running' job status, though the wait_s schema param covers that.

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?

Two dense but purposeful sentences; the scope condition is front-loaded and the sibling routing rule comes last. Slightly run-on phrasing around the parenthetical blocker list costs it a point, but every clause carries information.

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, so the description must carry the return contract itself, and it does: per-pad corridors, via-site verdicts, responsible blockers, CRAMPED classification, and actionable advice. The only gap is the async job lifecycle, which is handled by the wait_s parameter documentation rather than the description.

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 80%, so most parameters are already documented, giving a baseline of 3. The description repeats rather than extends what the schema says about nets and reach, adding no format or interaction detail (for example how max_nets interacts with nets, or how reach_mm changes CRAMPED verdicts).

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 and resource: per open net, report each pad's free escape corridors, whether a via can be dropped, and what blocks it. It also names concrete verdicts (CRAMPED) and the advice it returns, so the agent knows exactly what it gets back without opening the schema.

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?

Names the sibling alternative explicitly (repair_board) and the condition that selects this tool: a net that keeps failing. That is a clear when-to-use rule tied to a real tool in the sibling list, leaving nothing to inference.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true). It discloses atomicity ('Nothing is applied if any block fails to match'), the exactly-once whitespace-sensitive match rule, delete semantics via empty replace, and that every check is re-run. These are non-obvious behavioral traits an agent must know before invoking.

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?

Three tightly packed sentences, front-loaded with the action, then target resolution, then the critical match/atomicity rules. No filler; every clause carries information the agent needs.

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 mutation tool with no output schema, the description covers action, target file resolution, atomicity, match semantics, and check re-running. It omits failure/response details, but annotations and the atomicity statement cover the essentials.

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 baseline is 3, but the description adds real meaning: each search must match exactly once, matching is whitespace-sensitive, and an empty replace deletes. This meaningfully enriches the 'edits' array semantics beyond the schema's terse 'Ordered patches'.

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 and resource: 'Apply SEARCH/REPLACE patches to your latest script and re-run every check.' It also distinguishes itself from the sibling submit_circuit by describing the relationship ('as submit_circuit does'), so an agent can tell them apart without opening schemas.

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?

Clarifies which file is targeted ('your last submission when it was sent back (attempt_N_circuit.py), otherwise the design's circuit.py') and frames the tool as the alternative to submit_circuit for incremental editing. No explicit when-not condition is stated, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful scope detail (DNP parts excluded, artifact naming), but omits the asynchronous job behavior (a still-running job returns status 'running' and requires get_board_job follow-up), which is a key trait only found in the schema.

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?

Two tight sentences with the main action front-loaded and the artifact details immediately following. No wasted text.

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 tool with no output schema, the description names the output artifacts and exclusion rules, which suffices. The async nature is documented in the schema, so the remaining gap is minor.

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 100%, with both design_id and wait_s fully documented including the async follow-up semantics. The description adds nothing beyond the schema, so the baseline 3 applies.

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 and resource ('Export the assembled board as STEP') and clarifies what is included (3D models, DNP parts left out). It also names the resulting artifacts (workspace.step, workspace.zip), so an agent can distinguish this from render_board or get_downloads, though it does not explicitly contrast them.

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?

Usage is implied by the export/download framing, but there is no explicit when-to-use guidance, no conditions, and no mention of alternatives such as get_downloads for retrieving artifacts. The agent must infer the context.

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

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

Annotations declare it is a non-read-only, non-destructive, closed-world operation, matching "refill". The description adds the useful scope detail that ALL zones are refilled (no subset targeting), but says nothing about it being a potentially long-running job that may return status "running" and must be polled — that behavior lives only in the wait_s schema text.

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?

A single, front-loaded sentence with zero filler; the verb and scope appear immediately.

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 mutating, possibly async job with no output schema, the description covers only what. Workflow placement and the need to follow up with get_board_job on a "running" result are left to the parameter schema, which is thin compensation.

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 100%, so design_id and wait_s (including the running/polling semantics and the 55s cap) are fully documented in the schema. The description adds nothing on either parameter, which is acceptable at this coverage level but not value-adding.

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 ("Refill") and resource ("every copper zone"), plus the underlying engine (KiCad's zone filler), so the agent knows exactly what happens. It doesn't name the sibling boundary (e.g. set_zones defines zones, this recomputes fill), but the operation itself is unambiguous.

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?

No guidance on when to run it — not after routing, not after moving footprints, not after set_zones/set_keepouts changes — and no mention of alternatives or prerequisites. The agent must infer the workflow position from the sibling list alone.

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

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

Beyond the annotations, it discloses the mutation model: blocking copper is ripped (never a poured net), open nets are routed first, then ripped nets are rerouted around them. It also explains the quality gate—each round is kept only if KiCad counts fewer unconnected items—which is key behavioral context for a routing mutation tool.

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 core action, constraints, and usage guidance are front-loaded and information-dense. The semicolon-heavy single sentence and phrases like 'the way a designer does' make it slightly denser than necessary, but there is little true 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 routing mutation with eight parameters and no output schema, the description covers the essential process, preconditions, alternatives, and iteration behavior. It leaves return/status handling mostly to the wait_s schema text and get_board_job, and does not explain ml_options, so it is strong but not exhaustive.

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 high at 88%, so most parameter meaning is already supplied by the schema. The description adds useful semantics for `rounds`, including its relationship to route_board's default pipeline and the acceptance rule applied to each round, though it adds little for the remaining parameters such as wait_s, reach_mm, class_vias, vias_in_pads, or ml_options.

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 opens with a specific action—closing open nets left by routing—and explains the rip-and-reroute approach. It explicitly contrasts with repair_board, which never moves blockers, so an agent can distinguish it from route_board and related siblings without opening the schema.

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 states the exact triggering condition: use after route_board leaves a handful of nets open, noting route_board's default pipeline already runs three rounds. It also explains that this tool adds more rounds or follows a single route, and that repair_board is not the right alternative for moving blockers.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that by disclosing the input prerequisite and the shape of the data returned, though it says nothing about whether the plan is recomputed, error behavior, or staleness.

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?

It is two compact sentences with no filler; the returned-content list is front-loaded and the prerequisite is placed at the end. Slightly dense with parenthetical asides, but every clause carries information.

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 read-only getter with no output schema, the description does the necessary work of enumerating what the call returns (computed minimum board, pad density/fine-pitch/fanout stats, parts and nets, user instructions, plan schema rules) and states the precondition. An agent has enough to call it correctly, with only minor gaps around recomputation and failure modes.

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?

There is a single parameter (design_id) with 100% schema description coverage, so the schema already documents its format and provenance ('returned by create_design or list_designs'). The description adds no additional meaning about the parameter, which is the correct baseline when the schema does the work.

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 definition frames itself as 'What the board plan is decided from' and enumerates the returned content (minimum board, board stats, parts/nets, instructions, plan schema), which conveys the resource. However, it never states a plain verb ('returns'/'retrieves') and gives no differentiation from adjacent-sounding siblings like get_board_info or board_census, leaving the agent to infer the exact role.

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 gives one useful precondition, 'Needs an accepted schematic,' which implies the phase in which the tool is callable. It says nothing about when to prefer this over get_board_info, board_census, or get_workflow_guide, so selection among siblings must be inferred.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description contributes the return payload contract (what fields come back), which matters because there is no output schema, but it omits that a call can come back with status "running" and must be followed via get_board_job, and gives no sense of response size.

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?

It is a single run-on sentence that is a field inventory rather than a front-loaded statement of purpose; every item arguably earns its place given no output schema, but the lack of lead verb and the list-heavy structure make it harder to scan than it needs to be.

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?

Because there is no output schema, the description rightly spells out the returned contents, which is the main completeness win. It still leaves gaps: no indication of cost/size of an all-footprints dump, no guidance to use refs/include_footprints to trim the response, and no mention of the asynchronous running-status path.

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 refs, wait_s, design_id and include_footprints are already documented, and the schema's wait_s text carries the job-polling semantics. The description adds nothing parameter-level, such as that refs narrows the footprint list or that the full unfiltered dump can be large; baseline 3 applies.

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 resource is unmistakable: a full read-out of board state (layers, outline, rules, net classes, counts, footprints). However, it never names a verb and gives no differentiation from closely related siblings like get_board_context, board_census, or get_board_status, so an agent cannot tell from the description alone which snapshot tool to pick.

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?

There is no when-to-use guidance, no prerequisites, and no named alternative. The reader must infer from the sibling list whether this is the right inspector or whether board_census / get_board_context is cheaper for a narrower question.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the remaining burden is low. The description adds that a completed job yields a result or error and that the call blocks while waiting, but details like the 55s cap, restart survival, and budget behavior live only in the schema parameter text.

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?

Two short sentences that front-load the resource and outcome, with no filler. The second sentence overlaps with the wait_s schema description, which is a minor duplication but not bloat.

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, so the description correctly carries the return semantics (status now, result or error once finished) and the blocking behavior. It could say more about job lifecycle states or what 'latest' means when multiple jobs exist, but the essentials for calling it correctly are present.

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 100%, so the baseline is 3; the design_id and wait_s semantics (default 55, maximum 55, restart and budget behavior) are already thoroughly documented in the schema. The description's 'wait_s holds the call until it ends' restates what the schema says without adding format, deadline, or retry nuance.

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: it retrieves the design's latest board job, returning status and, on completion, result or error. That is clear enough to act on, but it offers no contrast with close siblings like get_board_status or get_board_info, leaving the agent to guess which status tool applies.

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 sentence 'wait_s holds the call until it ends' implies this is a blocking poll, and the schema param text explicitly says to follow a 'running' job with get_board_job again. However, the description itself never says when to prefer this over get_board_status, nor when long-polling is appropriate versus a quick check.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavior the annotations cannot express: wait_s blocks the call until the run ends or the timeout elapses, and the reported fields change depending on completion state (DRC-by-type, fab release, diagnosed causes appear only once finished, with a 'fix first' ordering). Return-format disclosure like this is the real value here.

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?

Two sentences, no filler, and the returned-field inventory is front-loaded before the wait_s semantics. The first sentence is a dense comma list, which is slightly heavy, but every item is informative rather than padded.

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, so the description carries the return-value burden, and it does so thoroughly: run state, metrics, DRC detail, release status, and failure causes with priority ordering. Combined with the explicit wait_s blocking rule, an agent has enough to call and interpret it. The only shortfall is the missing contrast with sibling status tools.

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 100% and both parameters are documented in the schema, so baseline is 3. The description only restates wait_s semantics ('holds the call until the run ends (or that many seconds pass)'), which is roughly what the schema already says ('Seconds to wait for a running board to finish (max 55)'), adding little new syntax or edge-case detail.

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 names the specific resource — the board run — and enumerates exactly what is reported (stage, size, layers, placement, routing completion, open nets, DRC counts, fab release, diagnosed causes). That is well beyond a restatement of the name. It does not, however, distinguish itself from close siblings such as get_fab_status, get_board_job, or board_census, so the agent cannot tell from the text alone which status endpoint to pick.

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?

Usage is only implied: the wait_s sentence signals this is polled until a run completes, which is useful. There is no explicit when-to-use guidance, no statement of when to prefer this over get_fab_status/get_board_job, and no prerequisites or exclusions. Adequate but with a clear routing gap.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds genuinely new context: refresh re-queries sellers and takes tens of seconds, which is a latency/cost disclosure the annotations cannot convey. It also describes the returned payload shape, useful since there is no output schema.

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?

Two compact sentences: the first establishes what the BOM contains, the second front-loads the one caveat (refresh cost). It is dense but every clause contributes; nothing is padding.

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?

With no output schema, the description appropriately carries the return-value burden by enumerating the line fields and totals. Combined with annotation coverage of the safety profile and a 100%-covered input schema, an agent has enough to call this correctly; only the absent when-to-use guidance leaves a real gap.

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 100%, so the schema already explains tier, boards, refresh, and design_id in detail. The description reinforces the refresh semantics (sellers re-queried) but adds no syntax or constraint beyond what the schema provides. Baseline 3 is appropriate when the schema carries the parameter burden.

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 names the resource (a live-priced BOM) and enumerates its contents concretely: references, value, footprint, chosen offer fields, alternatives, totals. An agent understands exactly what is returned. It does not, however, contrast itself with nearby siblings like consolidate_bom_basic or choose_bom_part, so it falls short of full sibling differentiation.

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?

There is no when-to-use guidance, no statement of prerequisites beyond the design_id parameter, and no routing to alternatives such as choose_bom_part or consolidate_bom_basic. The only usage-flavored content is the refresh cost note, which describes behavior rather than selection criteria.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that by disclosing what the response contains, including edge states such as 'accepted or the last blocking error' and the presence of a next-step recommendation. It stops short of describing pagination or refresh/caching behavior.

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?

One densely packed sentence, front-loaded with the core purpose, then a scannable list of returned sections. Every clause maps to a real output area; nothing is wasted, though the fragmentary 'Where a design stands:' construction is slightly informal.

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?

With no output schema, the description must carry the return-value burden, and it does so by enumerating the report sections an agent can expect. Combined with read-only annotations and a simple, fully documented single id parameter, an agent has what it needs to call the tool and interpret the result.

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?

There is a single parameter (design_id) and schema description coverage is 100%, with the schema itself explaining that the id comes from create_design or list_designs. The description adds nothing about the parameter, which is acceptable baseline behavior when the schema already carries the semantics.

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 names a concrete resource ('a design') and enumerates exactly what is reported (brief, schematic state, ERC, part/net counts, board run, readable files, next step), so an agent knows immediately this is a design status read. It does not, however, distinguish itself from nearby siblings such as get_board_status, get_board_context, or get_fab_status.

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?

Usage is implied by the content: you call it to see 'where a design stands' and the phrase 'the next step' hints it feeds a workflow decision. But there is no explicit when-to-use, no exclusions, and no named alternative among the many get_* status/info siblings, so the agent must infer routing on its own.

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

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

Annotations already declare readOnly/non-destructive/non-openWorld, so the bar is lower; the description still adds real value by disclosing the Authorization: Bearer requirement, the CLI invocation (`koppar download <design> <artifact>`), and that only currently-available artifacts are returned. It doesn't say whether URLs expire or how availability is signaled, keeping it out of 5 territory.

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?

Two tightly-packed sentences with the artifact list and availability caveat front-loaded, followed by the auth/CLI detail. No filler sentences and no repetition of structured fields.

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 simple read-only single-parameter tool, the description covers what is returned (URLs plus availability) and the auth/CLI path, which is sufficient without an output schema. A note on URL lifetime or the response shape would push it to complete.

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% with a single fully-described design_id, so the schema carries the parameter meaning and baseline is 3. The description adds no extra semantics (e.g., how design_id relates to artifacts or the artifact selector for the CLI) beyond what the schema already states.

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+resource (retrieve download URLs for a design) and enumerates the artifact types covered, which is more than a bare restatement of the name. However, it doesn't explicitly distinguish itself from overlapping siblings like get_bom or export_step, which also surface design artifacts, so the agent must infer the difference.

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?

Usage is implied (fetch links to artifacts) and it adds practical context about auth and the CLI equivalent, but there is no explicit when-to-use/when-not clause or routing to alternatives such as get_bom, export_step, or get_review_packet. The agent gets context but no decision rule.

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

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

Annotations already declare this as a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's added value is the disclosure of what it actually evaluates (serious DRC errors, unconnected items) and that it explains failures. That is genuine behavioral context beyond the annotations.

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?

A single front-loaded sentence that answers the primary question first and appends the failure case. No filler or redundant restatement of the title.

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?

With no output schema, the description must carry the return contract, and it does convey that the result is a boolean-like verdict plus reasons for failure. It stops short of describing the shape of those reasons or how this gates downstream fabrication/ordering steps, leaving a minor gap.

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?

There is a single parameter with 100% schema description coverage, including its pattern and provenance from create_design or list_designs. The description adds nothing about design_id, so baseline 3 applies since the schema does the work.

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 resource (fab release status) and defines the criteria being evaluated: zero serious DRC errors and nothing unconnected. This clearly distinguishes it from pure checkers like run_drc or check_net_rules, though it does not name a sibling explicitly, which keeps it just below a 5.

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 'earned its fab files' framing implies the tool is a pre-fabrication gate check, so usage is inferable. However, it never states when to call it versus get_board_status, run_drc, or the upload/order tools, and gives no exclusions or prerequisites.

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

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

Annotations already declare readOnly/non-destructive/closed-world, but the description goes well beyond them: it discloses the datasheet-database enrichment merged into topology_constraints, the footprint_suggestions, and critically that the 'custom' path returns an UNVERIFIED machine-extracted pinout that is 'not a symbol.' It also explains the design_id side effect (lookup recorded for the dossier; registered part belongs to the design). This is exactly the behavioral context annotations cannot carry.

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 return contents before the usage guidance and the custom-library edge case, and most sentences earn their place. There is mild redundancy (topology_constraints is introduced twice) and the run of clauses makes it denser than necessary, but it is well-structured overall.

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?

No output schema exists, yet the description covers the return contents (pins, description, topology_constraints, footprint_suggestions), the merge behavior, the custom fallback and its caveat, the batch form, and the design_id side effect. For a 4-param read tool with full schema coverage, nothing an agent needs to call it correctly is missing.

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 semantics the schema does not: the special library='custom' + name='<part number>' convention, the batch form of up to 12 (library, name) pairs, and the meaning of passing design_id. It stops short of describing error behavior for a not-found symbol, so not 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?

The description names a specific verb and resource ('Return the full pin list (number, name, electrical type) and description for a specific KiCad symbol') and clearly distinguishes itself from the sibling search_kicad_symbol by being a direct lookup and by handling the non-KiCad 'custom' fallback. An agent can tell it apart from create_custom_symbol and search_kicad_symbol without opening any schema.

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 when-to-use: 'Use this before writing pin connections ... so names, constraints and footprints match the symbol exactly.' It also names the routing condition to the alternative: for a part NOT in KiCad, call this with library='custom', then register with create_custom_symbol. When/when-not and the alternative tool are all stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety and external-dependency are covered. The description adds that the price pulls from vendors and a provider quote and hints at exclusions via 'what the total does not include', but the phrasing is vague and adds little concrete behavior beyond the annotations.

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?

A single front-loaded sentence beginning with the core outcome ('One price for a quantity') with no filler. The trailing clause 'and what the total does not include' is slightly awkward and underspecified, keeping it short of a 5.

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 read-only pricing tool with no output schema and full schema coverage, the description covers what the price comprises, which is adequate. It omits currency, whether the result is an estimate, and the provider prerequisite, leaving meaningful gaps for an agent deciding whether this is the right call.

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 all three parameters are already documented in the schema. The description alludes to quantity (boards) and the provider quote, matching the schema, but adds no syntax, format, or default details beyond it, so the baseline of 3 applies.

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 and resource: it returns 'one price for a quantity' and enumerates the components (parts, board/assembly from the provider quote, setup fees). This clearly separates it from get_bom or send_order_to_provider, though it never uses a crisp 'get the price for a design' verb+resource phrasing.

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 gives no when-to-use, when-not-to-use, or prerequisite guidance. It doesn't mention that a provider id (from list_order_providers) is needed, that requirement only living in the schema, and offers no routing against sibling tools like get_bom.

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

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

With readOnlyHint=true, destructiveHint=false and openWorldHint=false already declared, the safety profile is covered; the description usefully adds that this returns one consolidated text blob containing the netlist, dossier and reviewer instructions. It carries real return-content burden since no output schema exists, and it does so adequately.

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?

Two sentences, front-loaded with the packet's contents, and the second sentence pivots to the action step. Slightly dense parenthetical, but every clause conveys inventory the agent needs to decide whether to call it.

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 single-parameter read-only tool with no output schema, the description covers both what comes back and what to do next. Missing only explicit routing against lookalike siblings (get_design, read_design_file).

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?

One parameter with 100% schema description coverage, so the schema already defines design_id and its origin (create_design or list_designs). The description adds no further parameter guidance, which matches the baseline expectation when the schema does the heavy lifting.

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?

Names a specific resource (a design review packet) and enumerates its contents: brief, dossier, circuit.py, compiled connectivity with nets/pins/functions, and reviewer instructions. This distinguishes it well from file-level siblings like read_design_file, though it never explicitly contrasts itself with get_design or get_board_context.

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?

States the intended workflow ('Review it yourself and fix blockers with edit_circuit'), which tells the agent both the purpose and the follow-up tool. No explicit when-not or exclusion criteria are given, so it falls just short of full routing guidance.

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

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

Annotations already establish the safety profile (readOnly, non-destructive, non-open-world), so the burden is lower. The description adds that some stages are "each stage you do yourself," implying other stages are automated by sibling tools, which is useful framing, but says nothing about the guide's format, size, or caching behavior.

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?

A single dense sentence with the scope front-loaded and the usage rule last; every clause carries information. The nested parentheticals make it slightly hard to scan for a specific stage.

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 read-only single-enum guide lookup with no output schema, the description supplies the workflow framing, the stage vocabulary, and the when-to-call rule. Nothing essential to calling it correctly is missing, though the return shape is left implicit.

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% with a clear enum, so baseline is 3, but the description adds real meaning to four of the five enum values (synthesis = writing the SKiDL schematic, review = design review, etc.) that the bare enum strings do not convey. "overview" is left unexplained, a minor gap.

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 the resource clearly: end-to-end guidance for Koppar plus the per-stage instructions, and enumerates the stages (research, synthesis, review, board) that match the schema enum. It never uses a retrieval verb like "returns" or "fetches", but the content is unmistakable and no sibling tool overlaps with it.

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?

"Read the stage guide before doing that stage" gives an explicit trigger tied to each stage, which is genuinely actionable. It stops short of stating exclusions or pointing to alternative tools for stages handled automatically, so it is clear context rather than complete routing.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-open-world operation, so the bar is lower; the description still adds real behavior: an ~18 MB zipped payload limit, base64 encoding requirement, the folder contents expected, and the return value (design_id plus a first get_board_info). It does not discuss failure modes for oversized or malformed archives, which would have pushed it to a 5.

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?

Two sentences, both front-loaded and free of filler, with the input-mode split established early. The heavy nested parentheses and long run-on structure make it denser than necessary for a tool an agent must parse quickly.

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?

With no output schema, the description correctly fills that gap by stating what comes back (design_id and an initial get_board_info), and it covers both input modes and the size ceiling for a 7-parameter import tool. The absence of any note on which of the seven parameters are required, or what happens when both zip_base64 and from_design_id are supplied, is the main remaining hole.

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 86% schema coverage the baseline is 3, but the description adds meaning the schema does not: zip_base64 and from_design_id are presented as mutually exclusive input paths, and the ZIP is explained as a whole project folder rather than a bare board file. It never mentions board_file or new_project in prose, so those rely entirely on their schema descriptions.

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?

"Bring an existing KiCad project in as a board workspace" names a specific verb and resource, then immediately splits into the two input modes (ZIP folder vs. from_design_id), so the agent knows exactly what the tool produces (a workspace plus a design_id). It is clearly distinguishable from start_board (new board) and upload_board (pushing a board back).

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 states when to use each mode: a ZIP when the user has an existing folder on disk, and from_design_id when the goal is to change rules, place and route, and return the result via upload_board. It also explains the session_id revision-grouping rule. It lacks an explicit "do not use this if…" exclusion (e.g. when to use start_board or create_design instead), keeping it 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.

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

Annotations already establish that this is a non-read-only, non-destructive, non-open-world operation. The description adds useful behavioral context: the team reads every submission and the message should capture what happened in the user's own words.

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 description is front-loaded with the core action and then adds only relevant scoping, content, and usage details. Every sentence contributes to correct invocation without unnecessary repetition.

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 simple three-optional-parameter feedback tool with no output schema, the description covers purpose, trigger conditions, content expectations, and design scoping. It does not describe the post-submit response or privacy details, but annotations and schema cover the critical structured information.

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 100%, so each parameter is already documented in the schema. The description reinforces that rating, message, or both may be provided and that design_id scopes feedback to one design, but it adds little beyond the structured schema.

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 clearly states a specific verb and resource: send feedback to the Koppar team, either generally or about one design. It names the supported content types (rating, message, design_id) and is easily distinguishable from the hardware/design sibling tools.

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 gives explicit trigger conditions: use when the user asks to pass something on or describes what worked or did not work. It does not name alternatives or exclusions, but none are apparent among the siblings, so the guidance is clear without being fully exhaustive.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful domain behavior beyond that: results are ordered newest first, revision N is the board before change N, and revision 0 is the imported project. It does not describe the per-revision payload (id, timestamp, labels), which is the remaining gap given there is no output schema.

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?

Two compact clauses with zero filler; the ordering fact is front-loaded and the revision-numbering semantics and the restore cross-reference follow immediately. Every clause carries information an agent needs, and the semicolon-dense style is appropriate for a short definition.

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 one-parameter read-only listing with full schema coverage, the description supplies the two things that could not be inferred: result ordering and the meaning of revision indices including the base case. No output schema exists, but the notion of what a revision is and how it is numbered is explained well enough to consume the results 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% and the single design_id parameter is already documented in the schema with its source tools (import_kicad_project, list_designs) and a pattern constraint. The description adds no additional meaning about the parameter, so the baseline 3 applies.

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 the resource precisely ('the snapshots of this board') and adds ordering, making it immediately distinguishable from board-mutating siblings and from restore_board_revision. It lacks an explicit verb like 'list', so the listing action is inferred from the tool name rather than stated, which keeps it just under a 5.

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 names the alternative, restore_board_revision N, and ties it to a concrete purpose ('goes back to it'), so an agent knows this tool is for inspecting revisions before restoring one. There is no explicit 'use this when you need to...' framing or a statement of when not to use it, so it stops at clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that — result ordering (newest first), inclusion of web-app-created and board-workspace designs, and the fact that an agent can continue web-app designs. It omits pagination behavior and what identifying fields come back in each entry.

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?

Two compact sentences that front-load the result set and ordering. The parenthetical "(an agent can continue those too)" is a bit chatty but carries genuinely useful information, so it earns its place.

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 two-parameter read with no output schema, the description covers ordering and scope but not the shape of returned entries (e.g., whether design IDs are included so get_design can be called next). That omission is the main completeness gap for a discovery-style tool.

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 both limit and trashed are already documented, including the default of 20. The description's "With trashed, the designs in the trash instead" restates the schema rather than adding new meaning, so the baseline 3 applies.

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 the resource (the user's designs) and a scope detail (newest first, includes web-app and board-workspace designs), which clearly separates it from get_design, delete_design and restore_design. It never uses an explicit verb like "list", relying on the name/title for that, which slightly weakens the opening.

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?

Usage is implied: consult this to see the user's designs, and set trashed to view the trash instead. There is no explicit routing to siblings such as get_design for a single design, and no guidance on when a listing is preferable to fetching a specific design.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety and external-source nature are covered. The description adds a useful behavioral detail — results are time-sensitive ('today'), i.e., live availability rather than a static directory — plus that the response includes handoff information. It does not say whether a design must be loaded/selected for 'this kind of board' to resolve, which is a meaningful behavioral precondition.

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?

A single short sentence with no filler — appropriately sized for a zero-argument list tool. It is not strongly front-loaded though: the clarifying value ('can quote today', 'handoff') is buried in a trailing comma clause rather than leading.

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?

With no output schema, the description is the only source of return-value information, and it only loosely characterizes the response (providers, current quotability, handoff contents). Missing are the context dependency (which board is used) and its place in the order flow relative to get_order_price / send_order_to_provider, leaving the agent to guess on a workflow-critical step.

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?

Zero input parameters, so the schema carries no semantics to compensate for; baseline 4 applies. The description's implicit dependency on the current board context ('this kind of board') is worth noting but does not correspond to a parameter.

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 names the resource (PCB and assembly providers) and adds qualifying information (whether each can quote/take this board today), which hints at a capability listing. But it is a noun-phrase fragment with no verb, and the trailing clause 'what a handoff sends them' is opaque — an agent cannot confidently say whether this returns a provider list, a capability matrix, or a payload preview, nor how it differs from get_order_price.

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?

There is no statement of when to call this versus get_order_price or send_order_to_provider, which are the obvious neighbors in the ordering workflow. The agent must infer the sequencing on its own.

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

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

Goes well beyond the annotations (readOnly=false, destructive=false, openWorld=false): it documents that nothing is auto-legalized, that overlaps are deferred to run_drc, and that unknown references are reported back in 'missing'. It also explains the F/B side-flip behavior and relative-move semantics, which are genuine behavioral traits.

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 dense with zero filler; every clause (coordinates, rotation, side flip, relative moves, no legalization, missing refs) carries information. The telegraphic sentence-plus-fragment style is slightly cramped but earns its space.

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?

No output schema exists, yet the description still covers conventions, mutation semantics, and error signaling ('missing'). Async/job behavior is handled by the wait_s schema description pointing to get_board_job, so the definition is complete for correct invocation.

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 67%, and the description fills the semantic gaps richly: y grows downward, rotation is 'as KiCad shows it', side F/B flips the footprint, locked, and dx_mm/dy_mm/drot_deg are relative deltas from current position. This adds meaning well beyond the bare schema field names.

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+resource ('put footprints') with an explicit placement mode: exact, caller-supplied coordinates. The clause 'Nothing is nudged or legalized' separates it functionally from siblings like auto_place, anneal_place, and tidy_copper without needing to open their schemas.

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?

Makes clear this is the tool for deterministic coordinate placement rather than automatic/optimizing placement, and tells the agent overlaps are left for run_drc. It gives clear selection context but never names an alternative tool explicitly or states when NOT to use it (e.g. bulk placement).

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

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

Annotations declare destructiveHint=true, and the description earns that by disclosing the acceptance rule: new copper is kept only when KiCad counts fewer vias with no new open item or DRC error. That is meaningful behavior beyond the annotation. It does not say whether rejected copper is rolled back or how revisions/undo work, which keeps it below a 5.

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-loads the pipeline position and the core loop in one dense sentence, then adds follow-up and iteration advice in a short second clause. The nested parenthetical about pour islands is slightly hard to parse but carries information, so 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 13-parameter, destructive, no-output-schema tool, the description covers prerequisites, the accept/reject policy, the pour-island edge case, the polling follow-up and the verification step. An agent has enough to invoke it correctly and know what to do next.

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 already 85%, but the description adds real meaning: it explains that nets are tried 'most vias first' (max_nets/min_vias ordering), that via_cost is deliberately high for the lone reroute, and it supplies semantics for bridge_islands, which has no schema description at all.

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 and resource (rip one net at a time, reroute it alone, keep the new copper only on a via-count win) and explicitly positions itself in the pipeline 'After route_board and prune_vias', which separates it from prune_vias and route_board. An agent can tell what this does without opening the schema.

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 explicit preconditions (after route_board and prune_vias), the follow-up sequence (run_drc and get_score afterwards), and the caveat that a second pass sometimes finds more. It also names bridge_islands as the alternative for the pour-island case, so the routing decision between tools is spelled out.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description earns credit by explaining why a removal tool is non-destructive — a via survives if its removal disconnects anything, and zones are refilled and re-verified. It also discloses the runtime cost ('runs for minutes on a large board'), which annotations cannot express.

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?

Three dense sentences, front-loaded with the core behavior before the nets hint and the runtime/follow-up warning. Parentheticals are informative rather than filler; only the 'pours already join most of their pads' aside is arguably optional.

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 long-running mutation tool with no output schema, the description covers the decision rule (kept if removal disconnects), the runtime expectation, the long-job continuation hint exists in the schema, and the required follow-ups. It does not state what is returned (e.g. count of removed vias) or how partial/interrupted runs are reported, a minor gap.

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 50%: design_id and wait_s are documented in-schema, while nets and workers are not. The description adds real meaning for nets (candidate limiting, GND/plane rails prioritized) but says nothing about workers or about how nets interacts with the connectivity test. Baseline 3 given partial coverage.

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 and resource: 'Remove every via the board does not need', then defines 'redundant' concretely via the refill-and-compare-unconnected-count test. It never names the closest sibling (polish_vias), so an agent must infer the distinction itself.

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 a clear usage pattern: 'nets limits the candidates (GND and the plane rails first: pours already join most of their pads)' and names the follow-up sequence 'then fill_zones, run_drc'. No explicit when-not-to-use or exclusion versus polish_vias/tidy_copper, which keeps it below a 5.

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

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

Annotations already establish that this is a read-only, non-destructive operation. The description adds that it reads text files and identifies the specific artifact types available, but it does not describe error behavior, missing files, or authentication needs.

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 description is a single front-loaded sentence: it states the action first, then enumerates supported files. The list is long but every item is relevant to the tool's scope.

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 low-complexity, read-only file retrieval tool with annotations covering safety and a fully documented two-parameter schema, the description provides a complete catalog of readable design files. No output schema exists, so return-value details are not required.

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. The description adds substantial meaning beyond the schema by enumerating valid path values such as circuit.py, circuit.erc.json, and board_plan.json, which helps an agent know what can be requested.

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: reading a text file from a design. It enumerates the supported design artifacts, making the scope concrete, but it does not explicitly differentiate itself from siblings such as get_design or get_board_context.

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 lists what files can be read but gives no guidance on when to use this tool versus alternatives like get_design, get_board_context, or other retrieval tools. There is no mention of conditions, prerequisites, or exclusions.

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

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

Annotations already cover the safety profile (readOnlyHint true, destructive false, closed world), so the bar is lower; the description still adds real value by disclosing render semantics — facing layer at full strength with others faded — and the return payload (px_per_mm and region echoed, plus a downloadable workspace.render.png). It omits the async/job-follow-up behavior, which is only carried by the wait_s schema field.

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?

A dense but efficient paragraph that front-loads what the image contains before enumerating options and the return payload. Nearly every clause conveys distinct information, with only minor cramming of option descriptions into one sentence.

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?

With no output schema, the description correctly explains what comes back (scale, region, PNG download location) so a follow-up crop is exact. Combined with schema-level wait_s text about the running-job path, an agent has enough to call it, though the unexplained markers and max_width params leave small gaps.

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 only 21% across 14 params, and the description meaningfully compensates by naming and explaining side, region, drc_markers, ratsnest, highlight_nets/highlight_refs, layers, refs and courtyards. However, markers (custom annotations with labels) and max_width are never explained, and refs/courtyards are only implied by a list of drawing elements rather than described as toggles.

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+resource: an 'exact 2D picture of the board' with an enumerated layer set (copper, pads, vias, pours, outline, courtyards, refs). That makes it clearly distinct from data-oriented siblings like board_census or get_board_context, though it never names a sibling to differentiate against.

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?

Usage is implied through the option clauses ('drc_markers to circle every DRC violation', 'ratsnest to draw the open connections', 'region ... for a crop'), but there is no explicit statement of when to render versus using other board-inspection tools, nor any exclusion.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false), and the description adds a genuinely useful behavioral promise: existing copper for already-connected nets is preserved. Beyond that it is silent on what happens to nets that cannot be routed, whether changes are reversible, or that the job may need polling.

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?

Two compact clauses with the core behavior front-loaded and no filler. The route_board-with-preserve_existing framing is efficient, though the trailing 'with the learned router service' phrase adds little for an agent.

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?

No output schema exists, so the description carries the return-behavior burden, and it partially does by noting the default budget and long-running nature of the operation. That is adequate for a six-parameter repair tool, though it never says how an agent learns which nets remain open after the run.

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 67%, and the description contributes a default execution budget of 120 s, which the time_budget_s parameter does not document. It says nothing about nets, pours, or compact beyond what the schema already provides, so the baseline 3 fits.

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 action: preserve the copper of already-connected nets and route only the still-open ones, which is precisely 'route_board with preserve_existing'. That clearly separates it from plain route_board. It stops short of a 5 because 'the learned router service' is unexplained jargon and the net-selection scope is only implied.

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?

Usage is implied by the verbs 'keep' vs 'route the nets still open', so an agent can infer this is the repair path after routing. But there is no explicit when-to-use guidance: nothing says to run diagnose_open_nets first, nor when to prefer ripup_routing or a fresh route_board instead.

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

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

Goes beyond the annotations by disclosing the key side effect and safety property: the current board is snapshotted as a new revision first, so the mutation is reversible — consistent with destructiveHint=false. It does not mention permissions, concurrency with running jobs (wait_s/get_board_job), or failure behavior on an invalid revision, so it stops short of full disclosure.

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?

Two tight sentences, zero filler, with the core action front-loaded and the undo guarantee immediately after. Nothing repeated from the schema or title.

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 mutation tool with no output schema, the description covers what changes and how to revert it, which is the crucial gap. The asynchronous job semantics are delegated to the wait_s schema description, which is reasonable, though the description could have flagged that this may return a running job to follow with get_board_job.

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 67% and the undocumented parameters carry meaningful context: wait_s has a rich inline description and design_id identifies its origin. The description only adds the provenance hint that `revision` comes from list_board_revisions; it says nothing about valid revision values, wait_s semantics, or what the returned job status means.

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 and resource plus scope: put the board AND its rules back to a state from a named revision. It also names the source tool (list_board_revisions), which anchors the operation. It does not distinguish itself from the sibling restore_design, which an agent could plausibly confuse with this.

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?

Usage is only implied: the revision argument must come from list_board_revisions, which suggests a list-then-restore workflow. There is no explicit statement of when to prefer this over restore_design or other repair/restore siblings, and no stated preconditions (e.g., board must be idle, no job running).

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

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

Annotations already establish this is a non-read-only but non-destructive operation, so the description needed to add the meaningful behavioral context: what happens if the design is not in the trash, where it is restored to, and whether the restore is idempotent. None of that is present; 'put back' is only a restatement of the mutation the annotations already imply.

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?

One short sentence with no filler and the action front-loaded. It is not verbose, though the terseness comes at the cost of information rather than from efficient compression of useful detail.

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 single-parameter, non-destructive mutation with full schema coverage and annotations, the minimum is met but key behaviors remain unstated: failure mode when the design is not trashed, and what the caller gets back given there is no output schema. An agent could call it, but could not predict the outcome confidently.

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 100% for the single parameter, and the schema already explains that design_id comes from create_design or list_designs and enforces a pattern. The description adds nothing about the identifier, so the baseline 3 applies rather than a higher score.

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 concrete action (return a deleted design from the trash), which is more specific than the bare name, but it is essentially a paraphrase of the title 'Restore a design from the trash.' It gives no differentiation from nearby siblings such as restore_board_revision or delete_design, so an agent still has to infer which restore applies to designs vs. board revisions.

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?

There is no when-to-use guidance, no precondition (e.g., only works if the design is currently trashed), and no named alternative. The sibling list includes both restore_design and restore_board_revision, and this description does nothing to route between them.

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

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

Beyond the destructiveHint annotation, the description discloses exactly what can be destroyed: tracks, vias, and optionally copper zones. It also gives important protective semantics: keepouts are never deleted, locked items stay unless include_locked is set, and layers do not filter vias.

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 description is dense but front-loaded with the destructive action, and every clause carries operational meaning. It avoids repetition and covers the important caveats without unnecessary prose.

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 destructive bulk-delete tool with 10 parameters and no output schema, the description gives strong filtering and safety context. It leaves async job behavior and return handling to the schema's wait_s description and sibling tools, which is a minor gap rather than a blocking omission.

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 only 30% schema description coverage for 10 parameters, the description compensates well. It explains the boolean filters, default inclusion of tracks and vias, zone behavior, layer filtering exceptions for vias, filter combination, region matching, and include_locked semantics.

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 starts with a specific verb and resource: 'Delete tracks and vias', then enumerates the routing objects and filters affected. It is clear what the tool does, though it does not explicitly distinguish itself from nearby siblings such as prune_vias or cleanup_board.

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?

Usage is implied through the available filters ('of the given nets, on the given layers... or all') and defaults. However, the description does not explicitly say when to choose this instead of alternatives like cleanup_board, prune_vias, or route_board.

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

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

Far beyond the annotations, it discloses the wall-clock cap semantics (1200s default, 1500 max, ~20 minutes), that jobs survive a server restart and resume from their last finished stage, what preserve_existing=false actually overwrites ('routes every net again'), and what the result contains (unconnected items, DRC errors, per-stage counts, whether copper finishing was kept). This is unusually complete behavioral disclosure for a mutation tool.

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 default mode is helpfully front-loaded, but the body collapses into a single dense paragraph of long parenthetical sentences that an agent must parse linearly to find the mode switch. Every clause is substantive, yet the structure obscures the key decision rule more than it needs to.

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 an 18-parameter mutation tool with no output schema, it supplies the missing return-value picture (final unconnected items, DRC errors, pipeline summary counts) and the follow-up polling path. The only gap is that timing/async behavior of the single-route mode (default 120s, up to 900) is stated but its interaction with wait_s default 55 is left implicit.

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 18 parameters at 61% schema coverage, the description carries real weight: it explains the mode-switching behavior of nets/router, the conditional default of preserve_existing (keeps copper on a board with tracks, routes from scratch otherwise), pours='keep' defaulting on zoned boards, and that ml_options only applies to the learned router. It leaves compact, wait_s and vias_in_pads to their schema descriptions, and the generic 'rule overrides' shorthand never enumerates clearance/track/via/edge parameters.

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 opening sentence states a specific verb and resource ('Route under the project's rules and net classes') and the description carefully separates two operating modes: the default full pipeline versus a single route triggered by nets/router/single-route options. It does not name any rival sibling (e.g. ripup_routing, polish_vias) to steer an agent away from this tool, so it stops short of full sibling differentiation.

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 gives a precise trigger rule: with no nets, no router and no single-route option it runs the full pipeline; with nets, router or any single-route option it runs exactly ONE route, explicitly framed as 'expert control'. It also states defaults for preserve_existing, pours and the default time budgets, and directs the agent to get_board_job for polling.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower, and the description still adds real behavior: results are truncated to 'the first violations' with a default cap of 40, and a second mount_fit check is disclosed with its concrete tolerance (0.2 mm milling). It does not disclose that this is a long-running job whose result may come back as 'running' — that lives only in the wait_s schema text.

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 core purpose and output shape are front-loaded in the first clause, with the mount_fit addendum after. It is dense and long-ish, but nearly every clause carries information; the only soft spot is the mount_fit tangent competing with the primary DRC purpose.

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, so the description must explain the return value — and it does, enumerating counts by type, shorts, unconnected items, parity items, and truncated violation records with items and positions. The one gap, job follow-up via get_board_job, is covered by the wait_s schema text rather than the description.

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 50%: design_id and wait_s are documented, but types and max_violations are not. The description compensates by explaining that types is a filter over violation kinds and max_violations caps how many violations are returned, with a default of 40 — adding meaning beyond the bare integer bounds.

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 opens with a specific verb and resource — 'KiCad's DRC on the board as it is now' — plus the schematic-parity caveat, and it names the concrete outputs (counts by type, shorts, unconnected items, parity items, violations with positions). It never names the adjacent siblings (check_net_rules, check_physics, diagnose_open_nets), so the agent must infer the DRC-vs-rule-check distinction itself.

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?

'On the board as it is now' implies a post-edit / pre-signoff check, and the parity clause hints when the schematic is needed, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many check_* siblings. Usage 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.

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

Annotations declare write, non-destructive, closed-world, and the description substantiates that by spelling out merge semantics: verified pin tables are appended, and pre-existing verified entries for parts not re-looked-up are preserved. It does not state whether the markdown body overwrites the prior dossier, which is the one behavioral gap.

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?

Three sentences, front-loaded with the core action, and each sentence carries distinct information (format expectations, merge behavior, missing-part reporting). Dense but not padded, though the parenthetical heading list is slightly long.

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?

With no output schema, the description usefully covers the response surface by explaining that non-existent (library, name) entries are reported with catalog candidates. Combined with the annotation safety profile and full parameter coverage, only overwrite/versioning behavior is left unstated.

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 goes further by prescribing the required markdown section headings the 'markdown' string must contain and by framing 'design_id' in terms of the create_design/list_designs origin. This adds real meaning beyond the two terse schema descriptions.

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 ('Store') plus the exact resource ('the research dossier') and enumerates its expected section structure (## Parts list, ## Power rails, ## Topology constraints, ## Notes). No sibling tool competes for this action, so an agent can select it unambiguously.

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?

Usage is implied by the workflow reference ('as the research guide describes') and the prerequisite of having performed lookups, but there is no explicit when-to-use/when-not statement or named alternative. Adequate but leaves the trigger condition to inference.

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

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

Annotations already declare readOnly/openWorld=false/destructive=false, so the safety profile is covered. The description goes further by disclosing the return format, the near_misses behavior when no name matches every word, and the side-purpose of design_id, which is meaningful content beyond the annotations.

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?

Four sentences, all earning their place, front-loaded with the core action and return value before the fallback and design_id details. Slightly dense but no 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?

With no output schema, the description does the job of explaining the return shape and the near_misses fallback, plus how design_id affects recording. Complete enough to call correctly, though the exact result structure (list form, exact matches field) is left implicit.

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 baseline is 3, but the description adds real value: example query strings ('LGA-14', 'QFN-24', 'SOIC-8') and the purpose of design_id (lookup recorded for the design's dossier; a registered part belongs to it) beyond the schema's terse note.

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 and resource: 'Search KiCad's standard footprint libraries', and specifies the return type ('Library:Footprint' strings for the footprint= argument). The resource ('footprint libraries') naturally separates it from search_kicad_symbol, but it never explicitly contrasts with that sibling, so it stops short of a 5.

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 concrete query-construction guidance ('package family and pin count', optionally body size or pitch) and explains the near_misses fallback condition. It lacks an explicit when-not clause or a direct pointer to search_kicad_symbol for symbol lookups.

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

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

Annotations already declare it as a non-destructive, closed-world read. The description adds genuine side-effect context beyond them: passing design_id records the lookup in the design's dossier and scopes registered parts, and the fallback path to a custom component database is disclosed. It stops short of describing result shape or any limits, so not a 5.

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, then layered usage rules and fallbacks in a logical order. Each sentence carries practical information, though the closing sentence on design_id is dense enough that it could be tightened.

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?

With no output schema, the description carries return-value burden and does reasonably well by saying the search returns package-suffixed variants to prefer. A 3-param read tool with full schema coverage needs little more; only the absence of result-format/pagination detail keeps it from a 5.

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 baseline is 3. The description adds real meaning on top: query is a substring match, design_id ties the lookup to a design dossier, and library is implied as a restriction scope. It does not clarify maxLength/pattern constraints, but it exceeds the schema baseline.

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+resource+scope: searching KiCad's standard symbol libraries by name substring. It also distinguishes itself from siblings by name (get_kicad_symbol, create_custom_symbol), so an agent can tell it apart without opening schemas.

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 trigger ('use this whenever you are not 100% sure the (library, name) pair exists') plus branching guidance: prefer package-suffixed results, fall back to get_kicad_symbol(library='custom'), then register with create_custom_symbol. This is a full when/when-not/alternatives routing.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true; the description adds critical context beyond that: design data is published to a third party, the call is gated on explicit user request, and the return is a payment page. It also flags that some providers require shipping. This is exactly the extra context the annotations cannot carry.

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?

Three short sentences, front-loaded with the action and outcome, followed by the gating condition and a provider-specific caveat. No 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 destructive, open-world mutation with no output schema, the description covers what is sent, who receives it, the precondition, and what is returned (payment page). The only minor omission is error behavior on unsupported providers, but overall it is complete enough to invoke safely.

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 baseline is 3, but the description adds meaning: user_confirmed is tied to explicit user intent (beyond the schema's const:true), provider references list_order_providers, and shipping is conditional. It doesn't cover title or boards, but those are well-documented in the schema.

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?

Specific verb and resource ('Upload the released board ... to a manufacturer and return the page where the user pays') immediately distinguishes it from siblings like upload_board or get_order_price. The scope — publishing Gerbers, BOM, placement to a third party and handing off to a payment page — is clear.

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?

Explicitly says 'call it only when the user has explicitly asked to order from that provider, and set user_confirmed only then', and notes the shipping-address condition. This names the precondition and the confirmation requirement that select this tool over get_order_price or list_order_providers.

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

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

Discloses the key behavioral fact that existing Edge.Cuts content is wiped ('Replace everything'), which annotations alone do not convey. That sits in mild tension with destructiveHint=false and the description adds nothing about async job behavior, defaults (line_width_mm), or what happens on failure — those behaviors live only in the wait_s schema text.

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?

A single front-loaded sentence that leads with the verb and target layer, then the modes. It is dense with nested parentheticals but every clause supplies selection-relevant detail; nothing is padding.

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 mutation tool with no output schema, the description covers shape inputs and mutual exclusivity but not the return path (job / status / polling via get_board_job), the default line width, or failure handling. An agent would still need the schema to call this 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?

With schema coverage at 33%, the description carries real weight: it explains rect with optional corner_radius_mm, polygon as a point list, and fit_to_parts as the courtyard bounding rectangle plus margin_mm. It does not mention wait_s, line_width_mm, or design_id, but those are documented in the schema, so the gap is small.

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 and resource ('Replace everything on Edge.Cuts') and enumerates the three accepted outline forms (rect, polygon, fit_to_parts). Naming Edge.Cuts cleanly separates it from the set_keepouts / set_zones / set_silkscreen siblings without needing to reference them.

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 closing 'Give exactly one' is a useful exclusivity rule for the three modes, and each mode is described well enough to choose between them. However, there is no guidance on when to use this tool versus related siblings, no prerequisites (e.g., existing design state, required permissions), and no note on whether the change is reversible.

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