Koppar

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write-but-non-destructive profile is known. The description adds genuinely new behavioral facts: validation is skipped ('Nothing is checked here'), nets must pre-exist on the board, and sizes inherit from the board's current track/via defaults. It does not contradict the annotations, though it omits permission requirements and confirms the ripup undo path without detailing reversibility limits.

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 compact sentences, each earning its place: what it makes, how sizes default, the pre-condition, and the post-conditions. The core purpose is front-loaded before caveats.

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 and only a wait_s/job-follow-up mechanism documented in the schema, the description supplies the missing workflow context (validate with run_drc, undo with ripup_routing) plus defaults and pre-conditions. An agent could still want explicit return/status behavior beyond the schema's wait_s note, but the definition is substantially complete for a manual-edit 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 only 50%, so the description must compensate, and it does for the key gaps: it explains that width_mm, diameter_mm and drill_mm default to the board's current track/via sizes (functional defaults absent from the schema) and that nets must exist. It does not clarify the layer pattern for tracks or the points array shape beyond what the schema documents.

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 ('Lay exact copper by hand', tracks as polylines on a copper layer, and through vias) and positions it against the automated router siblings by scoping it to 'where the routers leave a gap'. An agent can distinguish this from route_board, add_project_files, or fill_zones 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 clear when-to-use context (manual copper where routers leave a gap) and names the lifecycle neighbors explicitly: run_drc afterwards to validate, ripup_routing to undo. It never names route_board/auto_place as the 'don't use this' alternative, so the exclusion 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 readOnlyHint=false and destructiveHint=false, so the mutation profile is covered. The description adds genuinely useful behavior beyond that: existing files are preserved unless overwrite is true, and the ZIP must be Base64 up to roughly 18 MB. It does not describe error behavior on size overflow, but the added semantics are solid.

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 tight sentences with the core action front-loaded ('Unpack a ZIP into the project folder'), followed by path-preservation detail and the overwrite/size constraints. No filler, though the colon-list of payload types is slightly dense.

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 annotations covering the safety profile and no output schema, the description supplies the missing behavioral context: overwrite semantics, size limit, and path-preservation. Return value needn't be described. Only failure-mode handling is absent.

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% (only design_id documented), so the description must compensate. It does for two of three params: overwrite's effect on existing files and zip_base64's format and size ceiling (matching the 24000000 maxLength). design_id is left to the schema, which is fine.

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 ('Unpack a ZIP into the project folder') and enumerates the concrete payload it distributes: footprints into a .pretty library, 3D models, and a library table. An agent knows exactly what the tool 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?

Usage is implied by the description (add files to an existing project) but no when-to-use or when-not guidance is given, and no sibling (e.g. import_kicad_project, create_design) is named as an alternative for the initial-import case. Adequate but leaves routing 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=false) by disclosing what is held fixed (edge connectors, fixed/locked parts), what is preserved (keepouts, courtyard gaps), the bottom-side via cost model, and that placement starts from current positions unless from_scratch. It stops short of saying whether the prior placement is recoverable or how the result is persisted.

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 purpose and constraints, then the comparison to auto_place, then the follow-up actions — a sensible order for a 28-parameter tool. The opening paragraph is long and clause-heavy, but nearly every clause carries information an 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 28-param mutation tool with nested objects and no output schema, the description covers the optimization behavior, the async job model (status "running", follow up via get_board_job), and the validation steps to run afterward. Return-value detail is thin, though the wait_s parameter partially covers it.

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 71% schema coverage the schema already carries most parameter meaning, but the description adds real semantics: flip_cost as mm-of-wirelength per bottom-side pad whose net has top-side pins, the coupling of keepouts to routing corridors, and the t0/refine interplay. Several params (seed, rotations, net_weight, split_cost) still get no prose explanation.

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 (dense placement) and method (simulated annealing) with the optimization objective (wirelength inside the outline) spelled out. It explicitly contrasts with the sibling auto_place ("slower... and much denser"), so an agent can distinguish the two without opening either 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 alternative (auto_place) and the tradeoff that selects this tool (denser but slower, with a concrete runtime figure), and says to follow up with overlapping_pairs and run_drc. It gives no explicit "when not to use" guidance or prerequisite statement beyond the schema-level design_id note.

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 this is a mutating but non-destructive operation; the description goes further by disclosing the default movement policy, which is the key behavioral risk an agent needs to know before invoking it. It stops short of describing job/wait semantics or what a completed placement looks like.

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 purpose and then constraint semantics; the constraint list is dense but every clause maps to real parameters. No filler, though the packed middle sentence is heavy to parse.

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 placement tool with no output schema, the description covers intent, default behavior, and the main constraint families, which is enough to call it correctly. The placer/refine tuning surface and the job/status flow are documented only in the schema, leaving minor 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 coverage is 77%, so a baseline of 3 applies, and the description adds real conceptual framing by grouping and glossing six parameters (fixed = exact origin positions, near = ref within maxMm of an anchor, edge = ref to left/right/top/bottom, keepouts, side, groups). The remaining 20 refined-annealing parameters are left entirely to 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 and resource ('pack footprints inside the board outline') and names the mechanism ('Koppar's heuristic placer, ratsnest-driven, courtyard-legal'). It also differentiates itself from the sibling placers by declaring itself 'coarse by design' and routing refinement to place_footprints.

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 default behavior (every unlocked footprint moves, locked ones stay) and the condition under which 'refs' overrides that default. It names one follow-up tool (place_footprints), but offers no when-not guidance nor mentions the sibling anneal_place or the in-tool placer/refine 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safe-read profile is covered. The description adds behavioral context by disclosing that output includes comparison bands against reference boards and a gap_to_designers list, but it stops short of describing return format or units.

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 dense sentence that front-loads the metric list before the comparison framing, with no filler. The heavy em-dash/list construction is compact though slightly run-on.

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 the burden of explaining returns and does enumerate the key outputs (metrics, designer bands, gap_to_designers list). It omits format/units detail, but for a read-only analysis tool with full annotation and schema coverage it is largely 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%: both design_id and wait_s (with its get_board_job follow-up) are documented in the schema itself. The description adds no parameter meaning beyond that, 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 names the concrete metrics it reports (signal vias per net, share of signal nets without a via, outer-layer copper share, vias in SMD pads, plane stitching) and frames them against designer-routed reference bands, so the agent knows this is a copper-quality census. It is clear but does not explicitly distinguish itself from nearby analysis siblings like score_board or check_physics.

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 reach for this tool versus score_board, check_physics, or check_net_rules, and no prerequisites or exclusions. The only routing hint (following a running job with get_board_job) lives in the schema, not the description.

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 readOnlyHint=false, but the description adds real substance beyond them: it modifies copper by inserting vias, constrains them to lie inside the island and inside the net's main copper on another layer, clear of other nets, and notably reports islands it found no site for (partial-failure behavior). The run_drc follow-up is a useful operational caveat.

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, all earning their place: the core operation, the failure-reporting behavior, and the run_drc imperative. Front-loaded with the operation, though the first sentence is dense with placement clauses that take effort to parse.

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 the return burden and does disclose that it reports islands with no viable site. Combined with the destructive annotation and the run_drc directive, an agent has enough to call it correctly; only the scope of nets (all nets when omitted) and the max_vias cap are 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 75% (nets, wait_s, and design_id are documented in-schema), so the schema does most of the work and baseline 3 applies. The description alludes to via count ('one through-via per island') but never clarifies max_vias, the one undocumented parameter, so it does not compensate for the remaining 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 a specific operation: placing one through-via per pour island that KiCad has cut off from its net, with concrete placement constraints. It is far more specific than a restatement of the name, though it opens with a dense clause ('A filled pour cut into islands by routing') rather than a clean verb+resource and never names a sibling to distinguish 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 by the scenario (islands cut off from their net after routing) and there is one workflow directive, 'Run run_drc afterwards.' However, there is no explicit when-to-use vs. when-not, and no comparison to conceptually adjacent siblings such as tie_rail_pads, tidy_copper, or ripup_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 cover the safety profile (destructiveHint false, openWorldHint false), and the description adds genuine behavioral detail beyond them: the exact metrics reported (narrowest track, length below class width, coupled share at diff_pair_gap, skew), the pair patterns recognized, and that routing applies the same rules. It is consistent with the annotations, though it never explains the non-read-only stance or the async job 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?

The purpose is correctly front-loaded and no sentence is wasted, but the core sentence is a dense colon-list run-on packed with parenthetical patterns and metrics that is hard to parse in one pass. It earns its length through real technical content but could be structured more readably.

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 enumerates what the check reports (narrowest track, below-width length, coupled share, skew), which is the key missing piece. Remaining gaps, the async job lifecycle and result shape, are partly covered by the wait_s schema text pointing to 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 description coverage is 100%, so both parameters (design_id, wait_s) are already fully documented in the schema. The description adds no parameter-level detail such as accepted id origins or wait semantics, 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 a specific verb and resource ('Check the copper against the project's net classes and differential pairs') and explicitly carves out the niche it fills versus a named sibling concept ('which KiCad's DRC does not'). An agent can distinguish it from run_drc, check_physics, or diagnose_open_nets 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?

It gives clear context for when this tool is the right one (net-class and diff-pair checks that DRC omits), which implies its place among the check_* siblings. It stops short of naming an alternative tool or stating when NOT to use it, so it is a strong 4 rather than 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 declare readOnlyHint=false and destructiveHint=false, so the write potential is flagged. The description adds real context beyond that: repair mutates the board in place, enumerates what changes (track width, skew meanders, return vias, widened rails), and gives the guard 'each kept only if KiCad counts nothing worse.' It doesn't cover auth or rate limits.

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 long clause list of checks is dense but each item earns its place as a distinct capability, and the conditional-execution caveat and repair semantics are front-loaded after it. No filler sentences.

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 covers the checks, the conditional execution rule, and the mutation behavior under repair; the wait_s param covers job follow-up via get_board_job. Return value shape is left implicit, which is a minor gap for a job-based 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 67%: design_id and wait_s are self-documented, but repair has no schema description. The description compensates by explaining what repair does and its safety condition, adding meaning beyond the bare boolean.

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 verb ('Judge the copper by physics') and enumerates exactly which physics checks run: impedance, IR drop, skew, return vias, 3W spacing, paddle via path. It explicitly distinguishes itself from KiCad's DRC, which is the natural alternative.

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?

Frames usage against KiCad's DRC ('which KiCad's DRC does not') and notes that finish_board runs the same repairs, giving the agent a clear routing signal. It does not state explicit when-not conditions or prerequisites beyond 'the board states something it can judge.'

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 annotation by disclosing the safety net: the board is rolled back if unconnected count or DRC errors rise, locked items are preserved, zones are refilled first so pours count, and contact is defined as KiCad copper overlap. This is exactly the behavioral context an agent needs before invoking a destructive mutation.

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 cleanup targets and dense with useful content; each sentence earns its place. It is a single dense block rather than cleanly structured, but there is little waste.

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 covers the safety rollback, preservation rules, and what list_removed reports. It omits the source of design_id and the default return of a normal run, but is otherwise complete for a destructive multi-flag mutation.

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 25% schema coverage, the description carries real weight: it explains what trim_overhangs does, that list_removed names removed items, that refill triggers zone refilling, and its prose maps to the dangling_tracks/duplicate_tracks/unconnected_vias toggles. It stops short of directly naming those three boolean flags, so it does not fully compensate for the coverage 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 (sweep/clean) and resource (routing) and enumerates exactly what is removed: zero-length and duplicate tracks, stub tracks, and vias meeting their net on fewer than two layers. An agent can distinguish this from sibling cleanup tools 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?

The description covers what the tool does in depth but never states when to reach for it over overlapping siblings like prune_vias, tidy_copper, repair_board, or ripup_routing. Usage is implied by the cleanup semantics rather than routed explicitly.

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 richly earns that by explaining what actually happens: both legs are ripped and routed alone, and the new copper is kept only if four conditions hold (gain >= min_gain_pct, skew within max_skew_mm, no new open items or DRC errors, no more than max_extra_vias added). It also explains the mechanism/rationale ('pairs routed with the whole board lose their lanes').

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 single dense paragraph is front-loaded with the precondition 'After route_board' and every clause carries a distinct fact (mechanism, acceptance criteria, rationale, companion tool). It is information-dense rather than bloated, though the long chained sentence could be split for readability.

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 12-parameter mutation tool with no output schema, the description covers purpose, ordering, and the keep/reject criteria well enough to call it safely. It omits any mention of the returned job status/wait behavior (partially covered by the wait_s schema) and what happens when no pair meets the bar.

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 83%, but the description goes further by weaving min_gain_pct, max_skew_mm, max_extra_vias, and target_pct into a single acceptance-criteria narrative, clarifying how they interact rather than restating each. It adds real meaning, though undocumented params like bridge_islands and ml_options go unexplained.

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 precise verb+resource (re-route weakly coupled differential pairs one at a time) and a scoping rule (least coupled first), immediately distinguishing it from siblings like route_board, ripup_routing, and check_net_rules. An agent can tell what this does without inspecting 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?

The opening 'After route_board' gives an explicit ordering precondition, and 'Run check_net_rules before and after' names adjacent tools. It stops short of stating when NOT to run it (e.g. before routing or on non-diff nets), so it is clear context rather than full exclusion 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 establish this is a non-read-only, non-destructive write; the description adds substantial context beyond them: the call is rejected without a footprint for 3+ pins, the symbol becomes available to the synthesizer as Part('custom','<name>'), it is added to the Verified parts table, and every pad including NC pins must be listed. That is exactly the preconditions and side effects an agent 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?

Front-loaded with purpose, then the critical constraint (footprint requirement), then effects. Every sentence carries information, though the density (multiple parenthetical asides and cross-references) makes it slightly heavier than necessary.

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 the resulting effect (symbol becomes synthesizer-accessible, added to Verified parts table). With constraints, preconditions, and outcome all covered for a 7-param write tool, nothing essential 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?

With 71% schema coverage the baseline is roughly 3, but the description goes further: it defines name as the part number, pins as the full datasheet pinout with every pad including NC, and footprint as a real in-library footprint. It omits guidance on datasheet, reference, and description params, but those are minor.

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: 'Register a connectable schematic symbol for a part that is NOT in KiCad's libraries'. It explicitly distinguishes itself from search_kicad_symbol (the sibling it responds to) and from the discrete-passive alternative approach, so an agent can tell it apart 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 when-to-use (specialty ICs, parts not in libraries), when-not (INSTEAD of telling the synthesizer to model the part with discrete passives), and the prerequisite discovery path (search_kicad_symbol returned nothing). It also routes to search_kicad_footprint for the required footprint argument.

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 safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds two genuinely non-structured behaviors: that it consumes no generation quota ('the work is done by you') and what it returns (design_id, web_url), which matters because 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?

Three tight sentences, front-loaded with the action, then the return values, then the quota note. Every sentence carries information and none repeats 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?

With no output schema, the description compensates by naming both returned values (design_id, web_url). Combined with brief content guidance and the quota note, an agent has everything needed to call this 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 coverage is already 100%, so the baseline is 3. The description still adds value by enumerating what the brief should cover ('what the board must do, its interfaces, power, size and constraints'), giving the agent concrete authoring guidance beyond the schema's generic wording.

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') and immediately elaborates on what the brief must contain (interfaces, power, size, constraints), so the agent knows exactly what this tool produces. It does not name the potentially overlapping siblings (start_board, submit_circuit), so it stops short of full 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?

The opening phrase 'Start a new design' implies the fresh-start context, but there is no explicit statement of when to use this versus siblings like start_board or submit_circuit. Usage is inferable rather than 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 establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description then adds real behavioral substance beyond that: it discloses the per-pad output (free corridors, via viability, blocker attribution to parts, nets, or board edge) and defines a domain term, CRAMPED, with its consequence. It does not cover timeout/polling behavior, though the schema's wait_s description partially does.

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 output contract, then the CRAMPED special case, then the sibling routing advice — no filler. The first sentence is a dense fragment ("For every net still open (or the nets named): each pad with...") that takes a second read, which keeps 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?

There is no output schema, so the description carries the full return-value burden and does so by describing the corridor/via/blocker breakdown and the CRAMPED verdict. For a read-only diagnostic with 80% schema coverage the definition is close to self-sufficient; only the undocumented max_nets parameter leaves a 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 80%, so the schema documents design_id, nets, wait_s, and reach_mm adequately; baseline is 3. The description reinforces the nets parameter (open nets vs named nets) and gestures at reach_mm via the corridor-free concept, but adds no syntax or format detail and never mentions max_nets.

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 (diagnose) and resource (open nets that won't route) and immediately enumerates what is inspected per pad: escape corridors on its own layer, via sites, and the specific blockers. An agent can distinguish it from route_board, repair_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?

Gives an explicit alternative and the condition that selects it: "Use it instead of repeating repair_board on a net that keeps failing." It also defines the default scope (every open net) versus the narrowed scope (the nets named), so the agent knows both when to reach for it and at what breadth.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real context: DNP parts are omitted from the export and the resulting artifacts are named workspace.step and workspace.zip. It does not, however, mention job/permission behavior beyond what the wait_s schema already covers.

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, front-loaded with the core action and scope, followed by the artifact naming detail. Every clause carries information; 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?

There is no output schema, and the description compensates by naming the returned artifacts (workspace.step, workspace.zip) and noting the DNP exclusion. Combined with the wait_s job-following note in the schema, an agent has enough to call and interpret the result, though the exact response shape is not spelled out.

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 both parameters (design_id, wait_s) are fully documented in the schema, including the job-following behavior for wait_s. The description adds no parameter-level meaning beyond that, which is the correct baseline 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?

States a specific verb+resource ('Export the assembled board as STEP') and qualifies the scope with parenthetical detail about 3D models and DNP exclusions. This clearly distinguishes it from siblings like render_board, upload_board, or get_downloads 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?

The purpose implies when to reach for it (you want a STEP 3D export), but there is no explicit when-to-use/when-not-to-use guidance and no named alternative for adjacent needs such as retrieving the artifact (get_downloads) or producing an image (render_board). Usage is inferred 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 this is a non-read-only but non-destructive mutation, so the safety profile is covered. The description adds that ALL zones are refilled (not a selective refill), which is useful scope context. However, it says nothing about the job's asynchronous nature, which only surfaces 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 no filler, and the scope word 'every' is well placed. It is arguably too terse for the async behavior, but there is 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 low-complexity two-parameter tool with a fully documented schema and no output schema, the description is close to sufficient. The main omission is that this spawns a pollable job, which the agent must piece together from the wait_s schema description rather than the tool 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 description coverage is 100%, so both parameters (design_id and wait_s, including the follow-up with get_board_job) are fully documented in the schema. The description adds no parameter meaning beyond that, 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 (refill) and resource (every copper zone) and names the underlying engine (KiCad's zone filler), which implies regeneration rather than zone creation. It is distinguishable from set_zones by the word 'refill', but the description never explicitly differentiates itself from that sibling.

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 use this tool versus alternatives like set_zones, route_board, or tidy_copper, and no mention of prerequisites such as needing an imported design or routed nets first. Usage is only implied by the verb.

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 readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description adds real behavior beyond that: the rip/re-route ordering, the safety carve-out (never a poured net), the improvement-gating ('each kept only if KiCad counts fewer unconnected items'), and the multi-round loop. It does not mention that the call is an async job followed via get_board_job, which is a notable behavioral gap for a mutating 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?

Front-loads the mechanism then ends with the usage/routing statement; every clause carries informational weight with no filler. The first sentence is a dense run-on, which slightly hurts readability, but nothing is 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?

For a 9-parameter mutating routing tool with no output schema, the description covers the crucial what/how/when and the key safety constraint. The remaining gaps are the async job model (wait_s / get_board_job), the undocumented nested `ml_options`, and implied prerequisites, so it is complete enough to invoke correctly but not fully self-contained.

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 78%, so most parameters are already documented. The description adds genuine meaning to `rounds` (a round is kept only if KiCad counts fewer unconnected items), but it adds nothing for `router`, `ml_options`, `class_vias`, `vias_in_pads`, `reach_mm`, or `time_budget_s`, which the schema covers. This is the baseline 3 for a mostly-schema-documented tool.

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 (closing/rerouting open nets after routing) and describes the exact mechanism: rip the copper blocking each open net, route the open nets first, then re-route the ripped nets. It explicitly distinguishes itself from siblings by naming route_board as the predecessor and repair_board as the contrast that never moves blockers.

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 trigger ('Use it after route_board leaves a handful of nets open') and an alternative contrast ('repair_board never moves the blockers'), which tells the agent when this tool is the right pick over repair_board. It stops short of an explicit when-not-to-use list or named prerequisites (e.g. board must already be routed), so it is strong but not 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 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, and openWorldHint=false, so the safety profile is covered. The description usefully adds the full scope of returned data, but says nothing about pagination, response size, or how the wait_s/running-job flow behaves beyond what the schema notes.

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 that leads with the board snapshot and then enumerates contents; efficient with no filler. It is somewhat run-on as a comma-separated list, which slightly hurts readability but wastes no words.

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 the burden of describing return values and does so thoroughly, including footprint attribute details. It leaves minor gaps around the asynchronous job model and result size, but the essential content an agent needs is 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 all four parameters (design_id, refs, wait_s, include_footprints) are already documented in the schema. The description's mention of 'every footprint' loosely relates to include_footprints/refs but adds no new parameter meaning, so 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 enumerates exactly what board data is returned (copper layers, outline, design rules, net classes, counts, zones/keepouts, footprints with attributes), so an agent can infer this is a read tool for a full board snapshot. However it is a noun-phrase listing with no verb and no differentiation from siblings like board_census or get_board_context, which also return board information.

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 use this tool versus alternatives such as board_census, get_board_context, or get_board_status, and no preconditions or exclusions. Usage must be entirely inferred from the field list.

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 safe read-only, non-destructive profile, so the bar is lower. The description still adds real behavior: the call can block on wait_s, and a job may return while still running, requiring a follow-up poll. It stops short of stating default/hard limits on waiting or what a partial result looks like.

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 terse sentences with no filler; the returned content is front-loaded before the blocking 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?

With no output schema, the description does carry the return-value burden and handles it: status, result, or error. Combined with the annotation safety profile and full schema coverage, an agent has enough to call it, though the running-state follow-up only appears in the schema 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 100%, so design_id and wait_s are fully documented in the schema, including the 55s default and the follow-up advice. The description's 'wait_s holds the call until it ends' largely restates that, adding no syntax or format detail 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?

Names a specific resource (the design's latest board job) and states exactly what is returned: status plus, once ended, result or error. It does not distinguish itself from the sibling get_board_status, which is a plausible source of confusion.

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 note says a still-running job should be followed with get_board_job. However, there is no explicit when-to-use guidance versus get_board_status or get_fab_status, so usage is only implied.

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?

With readOnlyHint=true, destructiveHint=false and openWorldHint=true already covering the safety profile, the description still adds real behavioral context: pricing is live, refresh re-queries external sellers, and that call takes tens of seconds. This latency/external-call disclosure is exactly the kind of value annotations cannot carry, though caching behavior beyond the refresh flag is 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?

Two sentences, no waste, front-loaded with the resource and its payload. The parenthetical enumeration is dense but each field listed earns its place because no output schema exists to describe the return shape.

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 fully substitutes by enumerating the per-line fields and totals; required/optional params are covered by the schema and the safety profile by annotations. The latency cost of refresh is disclosed, leaving nothing an agent needs to call 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 100%, so the schema already documents all three parameters and the baseline is 3. The description adds marginal but genuine semantics by qualifying refresh as a slow external re-query ('tens of seconds'), information absent from the schema's 'Ask the sellers again instead of the stored prices.'

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+resource ('live-priced BOM') and enumerates the exact contents of each line (references, value, footprint, offer details, alternatives, totals), so an agent knows what it returns without opening a schema. It does not explicitly contrast itself against nearby siblings such as choose_bom_part or get_order_price, which keeps it 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?

Usage is only implied: the description explains what 'refresh' does and that it costs tens of seconds, which implicitly guides when to set it, but there is no explicit when-to-use vs. alternative guidance or stated conditions for choosing this over get_order_price or choose_bom_part.

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 declare readOnlyHint=false, openWorldHint=false, destructiveHint=false, so the safety profile is partly covered. The description adds real behavioral detail beyond that: required input format (base64 ZIP with specific contents), a size ceiling (~18 MB), and the return value (design_id plus a first get_board_info).

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 densely packed sentences, front-loaded with the core action, with no filler. The format, size, CLI mapping, and return value each earn their 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?

No output schema exists, so disclosing the return (design_id and an initial get_board_info) is valuable and present. Format and size constraints are covered; only the ancillary parameters (brief, title) are left to the schema, which is acceptable.

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%, so the schema already documents most parameters. The description usefully clarifies zip_base64 (zipped folder, base64, ~18 MB) but says nothing about brief, title, or board_file, which the schema only partially explains. Baseline 3 is appropriate given the schema does most of 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 verb and resource ('Bring an existing KiCad project in as a board workspace') and scopes it to importing a full existing project, which separates it from creation/empty-board siblings like create_design or start_board. An agent can immediately tell what this does.

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 (import an existing KiCad project when you have a ZIP of one) but there is no explicit when/when-not guidance and no named alternatives among the many sibling tools (e.g. add_project_files, upload_board, create_design). The CLI hint (`koppar import <folder>`) adds some context but not 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 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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds two useful facts beyond annotations: results are newest-first, and web-app-created designs are included. It omits any pagination or default-limit behavior, but the schema covers the limit.

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 compact sentence with the key scope fact (newest first) front-loaded. The trailing parenthetical is slightly cryptic but not wasteful enough to penalize heavily.

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 list tool with annotations covering safety and a fully documented single parameter, the description is nearly sufficient. A brief note on default result size or that the returned IDs can be passed to get_design would have closed the remaining 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% and the single limit parameter is documented there as 'How many (default 20).' The description adds nothing about parameter semantics, 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 the resource (the user's designs) and the ordering (newest first), which is enough for an agent to distinguish it from the singular sibling get_design. The verb 'list' is implied by the name rather than stated, but the collection scope 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 when-to-use or when-not-to-use guidance. It does not route the agent between list_designs and get_design, nor mention create_design. The parenthetical about continuing web-app designs hints at a follow-on action but never names the tool that performs it.

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?

Annotations only cover the safety profile (non-read-only, non-destructive, closed-world), so the description usefully adds that no nudging/legalization occurs and that unknown references are returned in 'missing'. It does not state whether existing placements are overwritten or whether the operation is idempotent, leaving a modest 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?

Very dense and front-loaded — the core verb and coordinate semantics come first, then relative moves, then failure behavior. It is a long semicolon-chained sentence, but almost every clause carries information an 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?

There is no output schema, so the description's note about 'missing' references and the schema's wait_s/get_board_job follow-up cover the main return paths. Remaining gaps are minor: no mention of response shape beyond 'missing' and no limits on partial failure.

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 placement sub-fields have no schema descriptions at all, so the description carries the load: it explains mm origin coordinates with y growing downward, KiCad-convention rotation, F/B side flipping, locking, and the relative dx/dy/drot variants. This adds real 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?

States a specific verb and resource ('Put footprints exactly where given') and immediately pins down the coordinate frame, rotation convention and side semantics. The phrase 'Nothing is nudged or legalized' implicitly distinguishes it from auto_place/anneal_place, so an agent can separate it from siblings 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 clear usage context: exact placement, relative moves via dx_mm/dy_mm/drot_deg, and routes overlap checking to run_drc. It never explicitly names when to prefer auto_place or anneal_place over this tool, so no true alternatives/exclusions are 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?

With destructiveHint=true already declared, the description still adds real behavioral value: the keep-only-if-fewer-vias rule, the no-new-open-item/no-DRC-error gate, the island-bridging special case, and the honest non-determinism note on pours. It does not cover runtime/rate behavior or what happens on a partially applied run, so it is strong but not exhaustive.

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 dense paragraph that front-loads the workflow and keeps every clause earning its place; the parenthetical island note and the closing follow-up sentence are the only slightly crowded parts. Efficient despite covering a lot of ground.

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 14-param destructive mutation with a nested ml_options object and no output schema, the description supplies the essential workflow, safety gate, and follow-up calls. The gaps are limited to a handful of tuning parameters already documented in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 79% with 14 params, so most semantics live in the schema. The description adds conceptual meaning for via_cost ('high via price') and bridge_islands (one via per island) but says nothing about nets, pairs, router, wait_s, or the budget parameters, so it only marginally exceeds 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?

Names a specific verb (polish), resource (vias), and scope (net by net, fewest vias first), and the description makes clear it is a rip-reroute-keep loop rather than a plain router or prune. An agent can distinguish it from route_board, prune_vias, and ripup_routing 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?

States the prerequisites explicitly (after route_board and prune_vias) and the follow-ups (run_drc, get_score), plus notes a second pass sometimes finds more. The ordering and when-to-run context are fully spelled out rather than 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 declare readOnlyHint=false and destructiveHint=false, so the description's job is to add behavior beyond that. It does: the prune criterion is connectivity-based and conservative, zones are refilled and the unconnected count compared, and the run takes minutes on a large board, which is exactly the runtime expectation an agent needs. It does not note reversibility or that the board is modified in place, but the annotations plus this context cover most of the burden.

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 core action and its criterion, then the parameter hint, then runtime and follow-ups — no filler, 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 4-parameter, no-output-schema mutation tool, the description covers what changes (vias removed, zones refilled), how long it takes, and what to run next. It leaves the workers parameter and the return/status flow (running via get_board_job) only partially addressed in the description, but the schema covers wait_s.

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% (nets and workers are bare in the schema). The description compensates meaningfully for nets by explaining it as a candidate limiter and hinting GND/plane rails are the productive targets; wait_s and design_id are already documented in the schema. workers and the nets ordering priority are still left implicit, keeping this below 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?

States a specific verb+resource ('Remove every via the board does not need') with the deciding criterion spelled out (a via stays only if removing it disconnects something). This clearly distinguishes it from siblings like polish_vias and cleanup_board, which do not remove vias under a connectivity test.

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 selection guidance ('nets limits the candidates (GND and the plane rails first)') and a follow-up sequence ('then fill_zones, run_drc and score_board'). It stops short of naming alternatives it competes with (e.g., polish_vias) or stating when not to run it, so it is clear context but not full when/when-not coverage.

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 establish the safe read-only profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real context beyond them: what gets drawn, that the pixel-per-mm scale and region are returned for exact follow-up crops, and the concrete output location (workspace.render.png).

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 paragraph with the core purpose front-loaded and the option semantics following. Every clause carries information (feature list, options, output behavior, download path) and none 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?

With no output schema, the description carries the return burden and does so: it says the scale and region come back and where the PNG is downloaded. For a 14-parameter render tool the description, together with the schema-level notes on wait_s, region and design_id, covers enough 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 only 21%, so the description must compensate, and it largely does: it gives the enum for side, explains region as a mm crop, and clarifies what drc_markers, ratsnest, highlight_nets/highlight_refs (magenta) actually draw, plus refs, layers and courtyards in prose. Only markers, max_width and px_per_mm go unexplained, so it earns above the low-coverage 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 (render) and resource (board) with a clear qualifier (2D, exact). The feature list (copper per layer, pads, vias, pours, outline, courtyards, refs) lets an agent distinguish this visual-render sibling from analysis tools like board_census, get_board_info or check_physics 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?

Usage is implied ('as an engineer reads it', follow-up crops, visual inspection) but the description never states when to reach for this versus alternatives such as get_board_context, run_drc, or board_census. No exclusions or prerequisites are named, leaving routing 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 fix the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real behavioral context: the default learned router, what the 'ts' local router additionally does (keeps partial copper, last-chance welds, plane-island bridges), and the default time budget.

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 behavior before the router and budget details. Mostly earns its length, though the clause about welds and plane-island bridges is comparatively dense for a subordinate default.

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 6-parameter mutating tool with no output schema, the description covers router choice and budget but omits pours semantics and says nothing about failure/partial-completion behavior beyond the wait_s schema note pointing at 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 only 50% (nets, wait_s, design_id documented). The description compensates partially by explaining the router enum values and the default budget, but pours is left undefined in both places and the nets parameter semantics are not elaborated on.

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 pair — keep the copper of already-connected nets and route the still-open nets — and explicitly identifies the sibling it derives from ('route_board with preserve_existing'), so an agent can tell it apart from route_board without opening either 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 a router-selection rule ('ts' for the local router, learned service by default) but never states when to reach for repair_board versus ripup_routing, finish_board, or plain route_board. Usage is implied by the mechanics rather than 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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description adds the crucial behavioral fact that the current board is snapshotted as a new revision first, which explains why a board-overwriting operation is annotated non-destructive. It does not add what happens on conflict or failure, hence 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?

Two sentences, no waste, with the effect on the board front-loaded before the undo guarantee. Every sentence 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 mutating, potentially long-running restore with no output schema, the description covers the state change and the undo path, and the schema's wait_s covers the async follow-up via get_board_job. Missing only edge cases (invalid revision number, permission requirements).

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 67% — wait_s and design_id are documented in the schema, but 'revision' has no description anywhere. The description mentions revisions only as a concept, not as a parameter format (integer id), so it does not compensate for the gap. 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?

States a specific verb (restore) and resource (the board and its rules), plus the source of the revision. It cross-references list_board_revisions, so an agent can tell it apart from read-only sibling tools like list_board_revisions 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?

Clear context: use this with a revision obtained from list_board_revisions. That tells the agent the prerequisite and the source of the required 'revision' argument, but it gives no explicit when-not guidance or named alternative action (e.g., what to do instead if you just want to inspect a revision).

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 readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: vias are not layer-filtered, keepout areas are never removed, and locked items survive unless include_locked. It still doesn't state reversibility or whether the deletion can be undone, keeping it short of 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?

The text is dense and front-loaded, leading with the core action and then layering filter rules. Colon-and-parenthesis packing makes some sentences slow to parse, but essentially every clause carries information and nothing is 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 10-parameter destructive operation with no output schema and low schema coverage, the description covers the filter model, defaults, and protection rules (locked, keepouts) well. It omits what the call returns after deletion and any confirmation/undo expectations, which is a minor gap given annotations carry the destructive signal.

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 30%, so the description must carry the load, and it does: it explains the defaults for tracks/vias, the meaning of zones, that filters combine, that 'all' means unfiltered, and the region-matching rule for tracks versus zones. These are semantics the bare schema (booleans with no descriptions, a pattern-only layers array) does not supply.

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 set: 'Delete tracks and vias' plus zones, with filter semantics spelled out. An agent immediately knows this is a destructive geometry-removal tool. It does not name or contrast any sibling (e.g. prune_vias, cleanup_board, tidy_copper), so it stays at 4 rather than 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?

Usage is implied through filter semantics ('of the given nets, on the given layers, ... or all') and defaults ('tracks/vias ... both by default'), which lets an agent infer the rip-up-and-reroute workflow. However, there is no explicit when-to-use, when-not-to-use, or pointer to overlapping siblings like prune_vias or cleanup_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?

With readOnlyHint=false and destructiveHint=false already set, the description still adds real value: it discloses that preserve_existing defaults true and what copper it keeps vs replaces, that rule overrides are non-persistent, via_cost's default of 2 and its completion trade-off, and time_budget_s defaults (120, up to 900). It does not mention that the call is asynchronous/job-based, which is left to 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?

Given 21 parameters and a nested ml_options object, the length is defensible and the core purpose is front-loaded in the first clause. Several sentences are densely packed run-ons (the pours and via_cost sentences), but little is pure 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 21-parameter, nested-object, no-output-schema mutation, the description covers the main routing knobs but omits job/async behavior and expected runtime signal (the wait_s description carries that burden in the schema). An agent can invoke it, but must read the schema for the geometry and job-polling picture.

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 48%, so the description must compensate. It meaningfully explains nets, preserve_existing, pours, via_cost and time_budget_s (including defaults), but says nothing about the many geometry parameters (grid_mm, clearance_mm, track_width_mm, via_drill_mm, via_diameter_mm, edge_clearance_mm, negotiation_rounds). The vague line "Rule overrides apply to this run only" gestures at this group without naming which parameters it covers.

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 ("Route with Koppar's router under the project's rules and net classes") and immediately scopes it via nets/preserve_existing. It is clearly distinguishable from siblings like ripup_routing, polish_vias or tidy_copper, though it never names those alternatives explicitly, 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 conditional guidance for individual knobs ("preserve_existing (default true) keeps every track... and routes only what is still open", pours "keep" vs "engine") and notes rule overrides are run-scoped. However it never states when to pick this tool over ripup_routing, negotiated routing, or finish_board, so the routing workflow context is only implied.

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 read-only, non-destructive check, so the bar is lower. The description still adds valuable behavioral detail: default max of 40 violations, the types filter, schematic parity only when a schematic exists, and the mount-fit tolerance (0.2 mm) – all beyond what annotations provide. It does not explain whether the job runs synchronously or what status it returns, though the schema's wait_s description covers the async path.

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 covers the primary DRC capability, followed by a second labeled sentence for the mount_fit variant. It is front-loaded and free of filler, though the parenthetical defaults and tolerances make it slightly dense for a first read.

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 check tool with no output schema, the description is fairly complete: it names the report contents, the default capping behavior, the schematic-parity condition, and the extra mount-fit check. It does not describe the result shape or how types map to violation types, which would be needed for fully confident 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 50%: design_id and wait_s are documented in-schema, but types and max_violations lack schema descriptions. The description partially compensates by mentioning 'types filters' and 'max_violations caps (default 40)', adding meaning for both undocumented parameters. However, it does not clarify what type strings are valid or what the types array filters against, leaving the semantics incomplete.

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: runs KiCad's DRC on the current board, with schematic parity, and reports error/warning counts, shorts, unconnected items, and violations. It also names a distinct secondary capability (mount_fit 3D body vs cutout checking) that no sibling tool offers, distinguishing it from check_net_rules, check_physics, and diagnose_open_nets.

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 implies usage ('on the board as it is now') but never explicitly says when to use this versus alternatives like check_net_rules, diagnose_open_nets, or score_board. No exclusions or prerequisites are stated beyond the implicit need for an imported 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 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 only declare a safe read-only, non-open-world operation; the description goes further by disclosing what is included and excluded from the measurement (DNP parts omitted, parts with missing 3D models excluded from volume and reported separately). That is real behavioral context an agent cannot infer from readOnlyHint alone, though nothing is said about job timing or failure modes.

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 that front-load the action and then the output definition; the formula is worth its characters because it defines the tool's core value. It is slightly run-on and could be split for readability, but there is 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 takes on the return-value burden and does so thoroughly: it names every reported quantity and the missing-3D-model list. Combined with the schema's wait_s/job-polling note, an agent has everything needed to call it 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?

Schema description coverage is 100% for both parameters, including the design_id source and the wait_s/get_board_job follow-up, so the schema carries the parameter burden. The description adds no syntax, defaults, or format guidance beyond it, which is the expected baseline when coverage is complete.

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 pair (export the assembled board, measure it) and then enumerates the exact metrics produced: bounding-box size, volume, via count, copper layers, and a named composite score with its formula. That formula makes it trivially distinguishable from siblings like board_census or get_board_info, which cannot return this metric.

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 implies usage (you want the PCBGolf score / board measurement) but never states when to prefer this over board_census, get_board_info, or export_step, nor any prerequisites. The only routing guidance in the toolset lives in the schema's wait_s text pointing to get_board_job, not in the description.

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?

Goes beyond the annotations by disclosing that the operation overwrites the entire Edge.Cuts layer and that the three inputs are mutually exclusive, which the annotations (readOnlyHint=false, destructiveHint=false) do not convey. There is mild tension between 'Replace everything' and destructiveHint=false, and no statement about reversibility or permissions, so it is 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?

A single front-loaded sentence with the verb first, three compact parentheticals, and a closing constraint followed by a short imperative. Dense but every clause earns its place; 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 6-parameter, nested-object mutation with no output schema, it covers the mode selection and the exactly-one rule well enough for an agent to call it. The main gap is line_width_mm, which is explained nowhere, so the definition is not fully 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?

With schema coverage at 33%, the description carries real weight: it explains what rect, corner_radius_mm, polygon-as-points, and fit_to_parts/margin_mm mean, which the flattened schema leaves thin. It never mentions line_width_mm (undocumented anywhere) or design_id, leaving a 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 ('Replace everything on Edge.Cuts with a new outline') and enumerates the three outline modes, which cleanly separates it from siblings like set_zones/set_keepouts that also write geometry. It stops short of naming a sibling, so it is clear but not maximally disambiguated.

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, load-bearing usage rule: 'Give exactly one' of rect/polygon/fit_to_parts. It also implicitly tells the agent which mode to pick by describing each (rectangle, point polygon, auto-fit around courtyards). It does not state prerequisites or when to avoid this tool vs. alternatives, so it falls 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 only supply the safety triad (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds substantial behavior beyond that: changing copper_layers rebuilds the stackup, tracks on removed layers are reported, and copper_layers=1 forces single-face routing with no vias and removal of copper on the other face. That last point is a genuine side effect an agent must know before setting 1 layer.

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 purpose and preset semantics before the detail, and most sentences earn their place given 19 parameters and the tricky copper_layers=1 case. The final single-sided-board sentence is long and packs several conditional behaviors together, which costs some scannability.

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 and 21% schema coverage, the description covers the important behavioral consequences (stackup rebuild, removed-layer reporting, preset precedence) and the route_board/run_drc relationship. It does not describe the return payload or the wait_s/job-follow-up flow, leaving a small gap for an agent that needs to confirm the write succeeded.

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 19 parameters, so the description has to carry weight, and it does by explaining parameter families: min_* board minimums, default_* Default net class, named net classes with wildcard net patterns, and the preset's per-feature limits. It never enumerates the individual min_/default_ fields or the stackup/thickness interplay, so some parameters remain defined only by 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?

Opens with a specific verb+resource: 'Set the project design rules (.kicad_pro) and copper layer count.' It goes on to name the concrete artifacts it writes (.kicad_dru custom rules) and its downstream consumers (route_board, run_drc), so an agent can place it precisely among siblings like check_net_rules and set_keepouts.

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 operating context: route_board routes with these rules and run_drc checks against them, so the agent knows this must be configured upstream of routing/DRC, and 'explicit values override the minimums' resolves preset-vs-explicit precedence. It stops short of stating when to prefer this tool over a sibling or any prerequisites, so it is context without explicit 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 declare readOnlyHint=false and destructiveHint=false, and the description adds meaningful behavior beyond that: default layers (all), defaulted flags (no_tracks/no_vias/no_zone_fills all true), wildcard matching for remove, and enforcement by route_board and DRC. It doesn't disclose whether adds are additive or replace existing keepouts, leaving one notable 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?

Front-loads the purpose in the first clause, then packs defaults, enforcement, and the remove behavior into tight sentences. It is dense but every sentence carries information; 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 4-parameter write tool with no output schema, the description covers defaults, the rect/polygon shapes, layer targeting, enforcement, and removal semantics. It omits whether additions are additive versus replacing, and does not mention the wait_s job-follow-up behavior, which is 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 only 50%, but the description compensates by documenting defaults the schema omits (layers default to all; no_tracks/no_vias/no_zone_fills default true) and clarifying that remove takes names with wildcards. This adds genuine meaning over the raw 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 specific verbs (add/remove) plus the resource (keepout rule areas), and the body explains exactly what a keepout is and what it forbids. An agent can distinguish this from siblings like set_zones, set_design_rules, or route_board 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 clear context by explaining that route_board respects keepouts and KiCad DRC enforces them, which implies when they matter. It does not explicitly state when not to use this versus a sibling or any prerequisites, so it falls short of a full when/when-not/alternatives treatment.

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 establish this is a non-read-only but non-destructive mutation, and the description adds real behavioral detail beyond them: hidden fields, moved-to-fab-layer semantics, and the interaction with run_drc checks. It does not mention the async job behavior (wait_s / get_board_job follow-up), which is left to 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?

Compact and front-loaded: the core action leads, followed by per-parameter clauses in semicolon-separated form. Dense but every clause carries parameter meaning; the closing DRC note is the only sentence that is more contextual than operational.

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 and 40% schema coverage, the description covers the parameter effects and the DRC linkage well. Remaining gaps (async job follow-up, how to verify the result) are partly covered by the schema's wait_s 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 only 40%, so the description must compensate, and it does for three of five parameters, including defaults ('hide', 'keep') that are absent from the schema. It omits meaning for design_id and wait_s, but those carry their own 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?

The description names a specific verb and resource ('Take clutter off the silkscreen') and enumerates exactly which fields are affected (values, references, texts), which cleanly separates it from siblings like tidy_copper 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 only implied: the closing note that run_drc's silk_overlap/silk_over_copper warnings count what remains hints this is a post-DRC cleanup step, but there is no explicit when-to-use, when-not-to-use, or named alternative tool.

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 thin annotations it discloses real behavior: priority ordering (higher fills first), that clearance_mm/min_thickness_mm override rules, thermal=false for solid pad connection, and that remove never touches keepout areas. The only mild tension is remove deleting user zones while destructiveHint=false, but this is not a read/write reversal.

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 paragraph, front-loaded with the core action and followed by parameter and workflow semantics separated by semicolons. Every clause carries meaning, though the packing is heavy.

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 ordering, overrides, safety constraints, and the downstream workflow. It is largely sufficient for an agent to invoke correctly, missing only explicit alternative-tool routing.

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 50% schema coverage the description has to compensate, and it does: it explains priority, clearance_mm, min_thickness_mm, thermal, rect/polygon with the 'default whole board outline' behavior, and the remove name/wildcard syntax. design_id and wait_s remain schema-only but those are self-documented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.