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

Annotations already flag destructiveHint=true, so the safety profile is known. The description adds that it operates on the Edge.Cuts layer but does not disclose behavioral details such as whether it appends to or replaces an existing outline. No contradiction with annotations, but the added context is minimal.

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, efficient sentence that immediately conveys the core action and supported shape types. It contains no redundant or filler content.

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?

This tool has moderate complexity with nested parameters and multiple shape variants. The description is minimally adequate given the schema's completeness, but it lacks context about prerequisites (e.g., board must be open) and how it relates to sibling outline tools (clear_board_outline, replace_board_outline). The output schema exists but is not shown, so return values are not a concern.

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?

The input schema provides 100% coverage of all parameters with individual descriptions. The description adds no parameter-specific meaning beyond listing the shape names, so the baseline of 3 is appropriate.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Draw') and clearly identifies the resource ('PCB board outline' on the 'Edge.Cuts layer') and enumerates supported shapes (rectangle, rounded rectangle, circle, polygon). This distinguishes it from related tools like clear_board_outline and replace_board_outline.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It does not mention whether an existing outline is replaced, cleared, or whether the board must be open. The description merely states the action without any contextual or exclusionary cues.

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 include destructiveHint: true and readOnlyHint: false, so the mutating nature is known. The description adds no extra behavioral details like side effects, board requirements, or error conditions. It does not contradict 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?

The description is a single concise sentence (13 words) that front-loads the verb 'Add' and the resource, making it immediately understandable. No unnecessary 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?

With an output schema and well-documented parameters, the description is adequate for the tool's complexity. It conveys the core action and target clearly, though it lacks explicit prerequisites (e.g., requiring an open board) or behavioral caveats, which are minor for a simple add operation.

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 all 7 parameters described in the schema. The description itself does not add extra parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Add a text label to a PCB layer' with examples (silkscreen, fab, courtyard). This distinguishes it from similar tools like add_schematic_text, which targets schematics, and other board-adding tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context by specifying PCB layers, making it clear the tool is for board text, not schematic text. However, it does not explicitly mention alternatives or exclusions, such as 'use add_schematic_text for schematic text', so it lacks explicit 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?

Given annotations already declare destructiveHint=true and readOnlyHint=false, the description adds useful context: 'live via the KiCAD IPC API (changes appear instantly, no file conflicts).' It also specifies the target must be 'PLACED footprints,' which is critical behavioral information not present in annotations. It does not contradict 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?

The description is only two sentences, with the primary action and scope in the first sentence, and usage guidance in the second. No filler or redundancy; 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?

With a rich schema and output schema present, the description provides the essential context: what the tool does, when to use it, and how it behaves (live updates, no file conflicts). It also mentions the open-board context, which is important for statefulness. Nothing meaningful 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%, with every parameter (scale, offset, rotate, replace, modelPath, reference) having a clear description. The tool description itself does not add parameter-level detail beyond the schema, so the baseline 3 applies. It reinforces that reference can be '*', but this is already 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?

The description uses a specific verb 'Attach' and identifies the resource: '3D model to one or more PLACED footprints on the open board.' It distinguishes from sibling tool by stating 'for a library .kicad_mod use add_footprint_3d_model.' This clearly defines its scope and differentiates it from the library-focused 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?

Explicitly states when to use: 'Use this for components already on the PCB' and provides the alternative: 'for a library .kicad_mod use add_footprint_3d_model.' This directly guides the agent on tool selection versus a closely related 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?

The annotations indicate destructiveHint=true, but the description adds no behavioral context beyond that. It does not explain what destructive effects might occur, such as potential removal of existing copper or the need to refill zones. The description simply states the action without disclosing side effects.

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, concise sentence that front-loads the action and provides a clarifying parenthetical. It is appropriately sized with no wasted 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?

The description provides a clear basic purpose, and the schema and output schema fill in parameter and return details. However, it lacks usage context, such as when to use versus 'add_zone' or whether refilling is required, making it only minimally viable for a moderately complex PCB operation.

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?

The schema covers 100% of parameters with descriptions (net, layer, outline, clearance), so the description adds no additional parameter semantics beyond what is already in the schema. Baseline 3 is appropriate because 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?

The description clearly states the action ('Add') and the resource ('copper pour') and clarifies it as a ground/power plane. It is specific and unambiguous, but it does not explicitly distinguish from the sibling tool 'add_zone', which could be seen as overlapping, so it misses the top score.

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 usage guidance is provided. The description does not mention when to use this tool over alternatives like 'add_zone', nor does it indicate prerequisites, follow-up steps, or situations where this tool is appropriate.

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 mark the tool as destructive (destructiveHint: true). The description adds behavioral context by stating it can "replace" an existing model and by noting support for KiCAD path variables. It does not contradict annotations. It is transparent about the mutation and adds useful detail beyond the annotation flags.

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 three sentences, front-loaded with the core action, and contains no filler. Every sentence adds value: what it does, supported path variables, and when to use it. Excellent conciseness.

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 moderately complex tool with nested objects and an output schema, the description covers the essential context: purpose, timing (after create_footprint), and impact (3D viewer). It does not repeat parameter details (schema covers those), making it functionally complete for typical usage. Slight gap: no mention of what happens if the file or model is missing, but that is covered by the schema and annotations reasonably well.

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

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

Schema description coverage is 100%, with all properties documented. The description reinforces the path variable behavior already mentioned in modelPath's schema, but adds minimal new semantics. Baseline 3 is appropriate since 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?

The description clearly states the tool's action: "Attach (or replace) a 3D model — .step/.stp/.wrl — to a .kicad_mod footprint file." This is a specific verb+resource combination. It does not explicitly distinguish from sibling tools like import_3d_model or add_component_3d_model, but the target (a footprint file) is uniquely identified, giving strong clarity.

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?

Provides clear context: "Use this after create_footprint so the part shows up in the 3D viewer (Alt+3)." This gives a sequencing guideline and expected outcome. It does not mention exclusions or alternatives, so it stops short of a 5.

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

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

The description goes well beyond the annotations (which already mark it destructive) by explaining the collision-checking details, the PTH full-stackup penetration rationale, and the dryRun preview capability. It adds substantial behavioral context without contradicting 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?

The description is two sentences, compact and dense with value. It front-loads the core purpose, then adds strategy and safety details without any wasted 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?

The tool is complex (11 params, three strategies, collision checking), but the description covers the critical behavioral risks, strategy selection, and dryRun option. With a full input schema and an output schema present, it is sufficiently complete for an agent to understand the 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 description coverage is 100%, so the schema fully documents all 11 parameters. The description adds minimal parameter-level detail beyond what the schema already provides, mainly mentioning strategy names and dryRun, which are also 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?

The description opens with 'Drop GND stitching vias across the board', which is a specific verb+resource. It clearly distinguishes itself from single-via tools like add_via by describing multi-via stitching and strategies. The collision-checking emphasis reinforces its unique 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?

The description gives clear context about when to use it (stitching vias) and describes three combinable strategies and a dryRun mode, but it does not explicitly contrast with alternatives like add_via or state when not to use it. This is clear context without 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 indicate destructive and non-idempotent behavior. The description adds significant context about what gets modified: 'Adds the sheet box, name/file fields, a sheet_instances path entry on the next page number, and fixes sub-sheet component instance paths'. This goes beyond annotations and clarifies the side effects.

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 two sentences, front-loaded with the main action, and every clause adds value. No redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema, annotations, and schema descriptions, the description provides a strong overview of the tool's behavior and side effects. Minor gap: it doesn't explicitly mention potential failure modes or prerequisites beyond 'existing sub-sheet file', but overall it is complete for the tool's complexity.

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 description does not add new parameter-level semantics beyond the schema. It references 'sub-sheet file' and 'name/file fields', which map to existing schema descriptions but add no extra meaning. Baseline 3 is appropriate.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Insert a hierarchical-sheet reference block into a parent schematic' with specific additional actions listed. It distinguishes from siblings like create_hierarchical_subsheet by specifying 'pointing at an existing sub-sheet file'.

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 when to use the tool: when referencing an existing sub-sheet file and needing to fix instance paths for ERC. It provides clear context but does not explicitly name alternatives or exclusions, 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 already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds no further behavioral context, such as effects on existing layers, ordering constraints, or reversibility, but it doesn't contradict the annotations. Since annotations carry the safety profile, the minimal description is acceptable though not enriched.

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 sentence that leads with the action verb 'Add' and directly states the object and destination. Every word earns its place, with no filler or repetition. It is optimally sized for a tool with this level of complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there are 4 parameters with enums and an output schema, the description is adequate but incomplete. It does not explain the relationship between layer type (copper/technical/user/signal) and position (top/bottom/inner), nor when the optional 'number' parameter is needed. Since the output schema exists, return values are not an issue, but the tool could benefit from more guidance on parameter selection.

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

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

Schema description coverage is 100% with per-parameter descriptions in the input schema, so the baseline is 3. The description adds minimal semantic value by mentioning 'copper or technical' layer types, but it partially screens out 'user' and 'signal' enums. No additional parameter guidance is provided 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?

The description clearly states the action ('Add a new copper or technical layer') and the target ('PCB stackup'), distinguishing it from siblings like set_active_layer or get_layer_list. However, it omits the 'user' and 'signal' layer types that are allowed in the schema, making the stated scope slightly narrower than actual capability.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'to the PCB stackup' implies the tool is used for adding layers to the board, but it does not explicitly state when to use this tool versus alternatives, such as set_active_layer or get_layer_list. There is no mention of when not to use it or any preconditions like board state requirements.

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 mark this as destructive, and the description adds meaningful behavioral context: the property propagates to all instances, and the tool can update existing properties. It doesn't mention overwrite behavior explicitly but goes beyond mere annotation repetition.

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 action and context, no filler. Every word contributes to understanding the tool's purpose and effect.

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 7 parameters and a nested object, the description covers the key contextual point (library-level effect on all instances) and is backed by an output schema. It omits edge cases like missing symbols or library requirements, but remains adequate for typical use.

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 parameters are already documented. The description provides useful examples of property names but does not add deeper semantics for positional or boolean parameters. It meets the baseline for high schema coverage.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Add or update'), a resource ('custom property on a symbol definition in the lib_symbols section'), and the scope ('available to all instances'). It clearly distinguishes from sibling tools like add_symbol_property by focusing on library-level definitions.

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 context is clear: this tool operates on the symbol definition, not on schematic instances. It implies the use case for library-wide property changes. However, it does not explicitly name alternatives or say when not to use it, 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 already indicate destructive behavior (destructiveHint=true), and the description adds context by noting that it creates NPTH or PTH holes. However, it does not disclose other behavioral traits such as whether the operation is irreversible or what happens to existing board geometry. The description is consistent with the annotations, and the additional context about hole type provides some value beyond the structured data.

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 one concise sentence, directly front-loaded with the action and resource. It contains no redundancy or irrelevant information, making it easy to parse and understand quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and the fact that the output schema and annotations are available, the description is adequate to convey the core functionality. It covers the essential purpose and hole type. However, it could be slightly more explicit about the board modification aspect (though this is implied by the annotations) and might mention the optional padDiameter parameter for completeness, but this 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?

The input schema has 100% coverage with descriptions for all parameters (position, diameter, padDiameter). The description adds no new parameter semantics; it merely references 'specified position' but does not elaborate on units, relationships, or defaults. Since the schema already fully documents the parameters, the baseline of 3 is appropriate.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Place') and clearly identifies the resource ('mounting hole') and its purpose ('on the PCB'). It also distinguishes the tool from sibling placement tools like add_via by specifying that it creates NPTH or PTH mounting holes.

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 the tool should be used when a mounting hole needs to be placed on the PCB, but it does not explicitly state when to use it versus alternatives (e.g., add_via for vias). No exclusions or alternative tool recommendations are provided, though the tool's specific function makes the usage context 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 disclose destructiveHint=true and readOnly=false, but the description adds no detail about what destructive side effects might occur, such as overwriting an existing net with the same name or requiring a board to be editable. The word 'create' slightly conflicts with the destructive hint, but no explicit contradiction exists.

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 with no wasted words. It efficiently communicates the core function.

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 tool with only two parameters and an output schema present, the description is minimally viable. However, the destructiveHint annotation suggests that the tool might behave unexpectedly (e.g., on duplicate net names), and the description does not address this, leaving a contextual 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?

The input schema covers 100% of parameters with descriptions ('Net name' and 'Net class name'), so a baseline of 3 applies. The description does not add any additional parameter context beyond the schema.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('create') and the resource ('a new net on the PCB'). It is distinctly different from sibling tools like 'add_net_class' or 'create_netclass', which deal with net classes rather than 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?

There is no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, typical workflows, or compare with similar tools such as 'add_net_class' or 'assign_net_to_class'.

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

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

The description adds no behavioral context beyond the annotations. It doesn't address potential side effects such as overwriting existing net classes or how the tool interacts with current routing. Given annotations already flag destructiveHint=true, the lack of additional disclosure is a 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?

The description is a single concise sentence that directly communicates the core functionality without unnecessary detail. It is front-loaded and free of 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?

The description is minimal, relying heavily on schema and annotations. It doesn't explain important nuances like name conflicts, interaction with 'create_netclass', or whether any parameters are interdependent. Given the tool's complexity (9 params) and destructive hint, a bit more context would help.

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?

The input schema already includes descriptions for all 9 parameters (100% coverage). The description's mention of 'clearance, track-width, via, and differential-pair rules' maps to schema fields but doesn't add new meaning or clarify relationships between parameters.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb ('Create') and object ('named net class'), listing key parameters such as clearance, track-width, via, and differential-pair rules. However, it does not distinguish this tool from the sibling 'create_netclass', which likely serves a similar purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'create_netclass' or 'assign_net_to_class'. The description simply states the action without contextualizing its use cases.

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 description's safety burden is lower. It adds useful context about requiring the position to match the pin endpoint exactly and mentions ERC suppression, but it does not disclose side effects like overwriting existing flags or behavior on invalid input, leaving some opacity.

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 two sentences and front-loaded with the core purpose. The second sentence is slightly verbose with the capitalized 'PREFERRED' and repetition of 'exactly', but overall it is efficient and free of fluff.

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?

An output schema exists, so return values are covered elsewhere. The description adequately covers the two usage modes and the intended outcome (ERC suppression). It could mention error conditions or the batched alternative, but for a simple mutation tool it is sufficiently 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%, providing baseline 3. The description adds meaningful relationships between parameters, stating the preferred combination of componentRef + pinNumber and the alternative position, and emphasizes exact endpoint matching. This goes beyond the schema's individual field 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 clearly states the tool adds a no-connect flag (X marker) to a pin, with a specific verb and resource, and explains it suppresses ERC 'Pin not connected' errors. This distinguishes it from other schematic editing tools, though it does not explicitly differentiate from the sibling batch_add_no_connects.

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 clear guidance on how to specify the target pin (preferred componentRef + pinNumber, or alternative position) but does not mention when to choose this tool over batch_add_no_connects or any exclusion criteria. The context for use is implied (unused pins needing ERC suppression) but no alternatives are referenced.

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 indicate this is a mutating operation (readOnlyHint=false, destructiveHint=true). The description adds value by explaining the symbol format, but it does not disclose additional behavioral traits such as whether the schematic must be open, whether changes are saved immediately, or any side effects on existing components. No contradiction with 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?

The description is two concise sentences: the first states the primary action, the second provides a critical formatting rule with examples. No filler or redundant content.

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 a well-covered schema and output schema present, the description is sufficient for a basic add operation. However, it lacks usage guidance and does not clarify potential ambiguity with sibling tools like 'batch_add_components' or 'place_component,' leaving some contextual 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 100%, with every parameter having a description. The tool description largely repeats the 'symbol' parameter format already in the schema, adding no new meaning beyond what the schema provides. Therefore, the baseline of 3 is appropriate.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: 'Add a component to the schematic.' This unambiguously distinguishes it from board-level tools like 'place_component' and from other schematic tools like 'add_schematic_wire.'

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 (adding a component to a schematic) but does not explicitly state when to use this tool over alternatives, such as 'batch_add_components' for multiple components or 'place_component' for board placement. It offers no exclusions or alternative 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 indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context beyond the annotations, notably the requirement that 'the label text must exactly match the corresponding sheet pin name' and the role of hierarchical labels in linking sub-sheets to parents. No contradiction with 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?

The description is two concise sentences that front-load the purpose and then provide essential context. Every sentence earns its place with no redundant or filler content.

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 a destructive hint, output schema, and fully documented parameters, the description covers the key conceptual point (hierarchical labels and the matching requirement). It might benefit from mentioning prerequisites like an existing hierarchy, but the existing schema and annotations fill many gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not provide additional parameter details beyond the schema; the only extra nuance is the exact-match requirement for 'text', but that is already present in the schema's description for the text 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 clearly identifies the tool's function: 'Add a hierarchical label (sheet interface port) to a sub-sheet schematic.' It explains what a hierarchical label is and how it connects to the parent via sheet pins, which differentiates it from sibling tools like add_schematic_net_label or add_sheet_pin.

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 usage context is implied by the description: it is for adding hierarchical labels to sub-sheet schematics. However, it does not explicitly state when to use this tool over alternatives (e.g., net labels) or mention any 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?

Even with annotations already marking destructiveHint=true and readOnlyHint=false, the description adds substantial behavioral context: the exact-pin snapping guarantee, the failure mode of even 0.01mm offsets, and what fields the response will include (actual_position, snapped_to_pin). This goes well beyond the annotation flags and helps the agent anticipate tool behavior accurately.

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 three sentences, each earning its place: action, preferred approach, alternative, and response detail. Key information is front-loaded and the formatting with PREFERRED is scannable. No wasted 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?

For a 7-parameter tool with complete schema descriptions and an output schema, the description covers the critical operational guidance needed to use the tool correctly: how to guarantee a connection, precision requirements, and response fields. It is fully sufficient for an agent to select and invoke this tool accurately.

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 meaningful inter-parameter semantics: it explains how componentRef+pinNumber work together to snap the label, and that position must match the pin endpoint exactly. This clarifies relationships not evident from individual property descriptions, pushing above 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?

The description opens with a clear action: 'Add a net label to the schematic.' This specific verb+resource distinguishes it from siblings like add_schematic_component or add_schematic_wire. It also clarifies the tool's role in creating electrical labels, reinforced by the preferred snapping behavior and connection guarantee.

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 explicitly provides two usage paths: preferred componentRef+pinNumber and fallback position [x,y], with a clear warning about coordinate precision. It does not explicitly state when to use this tool instead of the sibling add_schematic_hierarchical_label, even though labelType supports hierarchical_label, leaving some ambiguity for that specific alternative.

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

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

The description adds the useful context that text annotations have no electrical significance, which is beyond the annotations (destructiveHint=true). It does not disclose file-saving requirements, reversibility, or side effects, but the destructive hint already signals mutation, so the additional context earns a mid-level score.

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 primary action, followed by usage examples and a clear distinction from net labels. Every sentence adds value with no redundancy.

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?

The description is sufficient for a tool with 8 parameters and an output schema. It provides the core purpose, usage guidance, and key distinction. It does not mention prerequisites like having a schematic open, but that is common to related tools and not a critical gap.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds no additional parameter-level meaning, such as coordinate system or units, beyond what the schema provides. 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?

Description clearly states the tool adds a free-form text annotation to the schematic, with a specific verb and resource. It distinguishes from net labels by noting text annotations have no electrical significance, which also differentiates it from the sibling tool add_schematic_net_label.

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 explicitly says 'Use this to add notes, labels, section headings, or documentation strings' and contrasts with net labels, implying when not to use it. However, it does not explicitly name an alternative tool or provide an exclusionary 'do not use for' scenario beyond the net label distinction.

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

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

The annotations already mark this as destructive (destructiveHint=true). The description adds valuable behavioral context beyond the annotations: snapToPins corrects float imprecision by snapping endpoints to exact pin coordinates, and intermediate waypoints are never snapped. This clarifies the tool's actual behavior. It doesn't discuss undoability or side effects, but the annotation covers the core destructive nature.

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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by a mandatory prerequisite, then snapping behavior, a routing example, and a final clarification. Every sentence earns its place, and the structure is logical and easy to follow.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (coordinate-based wiring with snapping nuances), the description covers all essential aspects: what it does, prerequisite steps, snapping behavior, intermediate waypoint handling, and a concrete example. With a present output schema and full parameter coverage, the description is complete for an agent to select and invoke the tool correctly.

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

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

The schema provides 100% coverage for all four parameters. The description adds meaningful semantics beyond the schema: it explains how waypoints are interpreted (first/last snapped, intermediate not) and gives a routing example. It also names snapToPins default behavior and clarifies that it only affects endpoints. This adds real value to the parameter understanding.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb and resource: 'Draws a wire on the schematic between two or more coordinate points.' It also distinguishes itself from siblings like delete_schematic_wire and route_trace by specifying the schematic context and the coordinate-based approach.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'Always call get_schematic_pin_locations first to get the approximate pin coordinates, then pass them as the first and last waypoints.' It also explains how to route around components with intermediate waypoints, giving a concrete example. This is clear, actionable guidance with no ambiguity.

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 flag this as destructive (destructiveHint=true) and not read-only, so the safety profile is known. The description adds the key constraint that pinName must exactly match a hierarchical_label in the sub-sheet, and explains what sheet pins are. However, it does not mention potential failure modes, whether existing pins are affected, or any side effects beyond adding a pin.

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 two sentences, front-loaded with the action ('Add a pin...') followed by a crisp explanation of sheet pins and the matching requirement. No filler or redundant content.

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?

The description covers the core operation and a critical constraint. With an output schema present, return values are handled there. It could mention prerequisites like having an existing sheet symbol, but the matching constraint implies the sub-sheet must exist, making this reasonably complete for a focused mutation 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 description coverage is 100%, so the baseline is 3. The description reiterates the pinName matching constraint (already in the schema) but adds no new parameter-level semantics. It provides useful context about the parent-side role of the pin, but this does not meaningfully extend what the schema already 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?

The description opens with a specific verb and resource: 'Add a pin to a sheet symbol block on the parent schematic.' It clearly distinguishes this from sibling tools like add_hierarchical_sheet (which adds the sheet itself) and add_schematic_hierarchical_label (which adds labels in the sub-sheet) by stating these are parent-side connection points.

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 clear context: this is for parent schematic pins that correspond to sub-sheet hierarchical labels. It implies the workflow (must have a sub-sheet with matching labels) and does not explicitly name alternatives or exclusion criteria, but the context is sufficient for an agent to select this tool over related ones.

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 indicate destructiveHint=true and readOnlyHint=false, so the mutation aspect is covered. The description adds that it works on a .kicad_sym file and can 'update' existing properties, but it does not disclose whether an existing property is overwritten without warning or whether file modifications are permanent beyond what the destructive hint implies.

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 that clearly communicates the tool's purpose without redundancy. It includes useful examples and the file type, making it efficient and well-structured.

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?

The tool has a rich input schema and an output schema, so the description does not need to explain return values. However, given the existence of a very similar sibling tool ('add_library_symbol_property'), the description lacks enough contextual detail to guide an agent in selecting this specific variant, and it omits any mention of side effects beyond the annotations.

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?

The input schema covers all six parameters with descriptions, so schema_description_coverage is 100%. The description provides examples of property names but does not add meaningful semantic information beyond the schema, such as coordinate units or behavior of optional fields like 'hide' and 'position'.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Add or update') and the resource ('custom property on a symbol in a .kicad_sym library file'), with examples like Manufacturer and MPN. It is specific and actionable, but it does not explicitly distinguish itself from the sibling tool 'add_library_symbol_property', which may perform a similar operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use this tool versus alternatives such as 'add_library_symbol_property' or 'update_symbol_from_library'. The description only states what the tool does, not the context in which it should be chosen.

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 base safety profile is known. The description adds no extra behavioral context, such as whether the via is automatically connected to the provided net, how layer selection works, or what side effects occur (e.g., DRC implications). It does not contradict annotations but also does not build on them.

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 extremely concise ('Add a via to the PCB' — six words) and front-loaded. Every word is necessary; there is no redundancy or filler. It is appropriately sized for the simple operation it describes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has multiple parameters, nested objects, an output schema, and many sibling tools, the description is too sparse. It omits critical behavioral context such as coordinate interpretation, net existence requirements, and how this differs from adding arrays of vias (add_gnd_stitching_vias). For a board-modifying tool, more context would help the agent invoke it correctly.

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

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

The input schema provides descriptions for all three parameters (net, viaType, position) with 100% coverage. The description 'Add a via to the PCB' does not add any parameter-level meaning, so a baseline score of 3 is appropriate where 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?

The description 'Add a via to the PCB' uses a specific verb ('Add') and resource ('via') with a clear target (PCB). It distinguishes from sibling tools like add_mounting_hole and add_board_outline by naming a unique PCB element, making the purpose 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?

The description gives no guidance on when to use this tool versus alternatives such as add_gnd_stitching_vias (which also adds vias) or route_trace. It does not mention prerequisites (e.g., an open board) or provide any when-not-to-use instructions.

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 known. The description adds no extra behavioral context such as whether this modifies the board, requires a refill, or is undoable. It does not contradict annotations, but it also does not go beyond them. For a mutation tool, more disclosure (e.g., what happens to existing zones or nets) would be helpful.

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, focused sentence that immediately states the verb, object, and key modifiers. It is concise with no redundant information, and the structure front-loads the essential purpose. Ideal for quick agent comprehension.

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?

Although the output schema exists and annotations cover destructive behavior, the description lacks important contextual information such as when this tool should be used, how it relates to the sibling 'add_copper_pour', and any side effects like needing to refill zones. This leaves the agent underinformed for selecting and invoking the tool correctly in a broader workflow.

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

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

Schema description coverage is 100%, with all six parameters described in the input schema. The description itself adds no parameter-level detail beyond what the schema provides. Since the schema carries the full burden, a baseline of 3 is appropriate.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (create) and the resource (copper fill zone/pour) with a specific context (on a PCB layer for a specified net). It is not a tautology and conveys what the tool does. However, it does not distinguish from the sibling tool 'add_copper_pour', which appears to have the same purpose, so it lacks explicit 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?

The description provides no guidance on when to use this tool versus alternatives like 'add_copper_pour' or when not to use it. There is no mention of prerequisites (e.g., board must be open) or relationships to other zone-related tools (e.g., 'refill_zones'). The usage context is only implied by the name and 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 mark the tool as destructive and non-read-only, but the description adds no behavioral context beyond that. It does not explain that components will be repositioned, how the referenceComponent anchors alignment, or what happens to existing placements. No annotation contradiction exists.

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, focused sentence that front-loads the action and key options. It avoids redundancy with the schema and contains 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?

The tool has moderate complexity with four parameters, an output schema, and annotations, all of which cover most contextual needs. The description conveys the core operation effectively, though it relies on the schema for parameter details and offers no guidance on referenceComponent semantics or when to use the 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?

The input schema has 100% coverage with meaningful descriptions for all parameters, including the enum for alignmentType and the unit for spacing. The description adds no parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool aligns multiple PCB components and enumerates the alignment modes (horizontal, vertical, grid) plus optional spacing. It is specific about the action and resource, but it does not explicitly distinguish this from sibling tools like batch_move_components or place_component_array.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as batch_move_components or place_component_array. There are no preconditions, exclusions, or examples of appropriate use beyond the implied meaning of the name and 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 indicate destructiveHint=true and readOnlyHint=false, so the mutation aspect is covered. The description adds the ordering dependency (must be called before other tools), which is valuable 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?

Two concise sentences, front-loaded with the action and example. Every word earns its place, with no redundancy or 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 simple one-parameter tool with an output schema, the description fully covers purpose, usage timing, and effect. It is complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% for the only parameter (schematicPath), and the schema already provides a clear description. The tool description does not need to add parameter details, so baseline score 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?

The description clearly specifies the action ('Assign reference designators') and the target ('unannotated components'), with a concrete example (R? → R1, R2). This distinguishes it from all sibling tools, as no other tool performs annotation.

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 usage guidance is provided: 'Must be called before tools that require known references.' This tells the agent when to invoke this tool and implies that it is a prerequisite for other operations, which is sufficient given the tool's unique role.

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 indicate the operation is destructive (destructiveHint=true) and non-read-only. The description adds minimal behavioral context beyond stating the purpose. It does not mention what happens if the net is already assigned to another class, which would be useful but is not required given 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 sentence that is concise, front-loaded with the action, and contains no redundant information. Every word 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 simple two-parameter tool with a complete schema and annotations, the description is sufficient. It could mention the consequences of reassigning a net (e.g., it is removed from any prior class), but the existing annotations cover the destructive nature, making the description adequately 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?

The input schema fully describes both parameters ('Name of the net' and 'Name of the net class'). The description does not add any parameter-level detail, so it provides no added value beyond the schema, resulting in the baseline score.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Assign a net to an existing net class') and its purpose ('to apply its specific design rules'). It uses a specific verb and resource, and distinguishes from siblings like create_netclass or add_net by emphasizing 'existing net class'.

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 clear context: assign an existing net to an existing net class. It implicitly differentiates from tools that create net classes (create_netclass) by saying 'existing', but it does not explicitly mention alternatives 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 declare destructiveHint=true and readOnlyHint=false. The description adds meaningful behavioral context beyond annotations: it specifies the heuristic (avoid collisions with components/net labels), the net-label awareness compared to KiCAD, and the optional limitation by references. This adds value without contradicting 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?

The description is two sentences, front-loaded with the primary action, and every phrase earns its place. It packs a lot of semantic content (what, where, how, and optionality) into a compact, readable form without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 parameters, an output schema, and moderate complexity, the description covers the core algorithm, constraints, and optional filtering. It doesn't describe the return value, but the output schema likely covers that. It also doesn't mention prerequisites like whether the schematic must be open, but the file path parameter implies direct file editing. Overall, sufficiently complete for selection and 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 description coverage is 100%, so the schema already documents all parameters. The description independently mentions 'Optionally limit to specific references,' reinforcing the references parameter, but adds no new parameter details beyond what the schema provides. Baseline 3 is appropriate.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('reposition'), names the exact resources ('Reference and Value field'), and describes the outcome (outside body and net labels, avoiding collisions). It also distinguishes itself from sibling tools by focusing on field auto-placement rather than component or net label movement, making it unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use it ('Automatically reposition...', 'Like KiCAD's built-in field auto-placement but net-label aware') and implies it is for cleaning up field placement. However, it does not explicitly mention alternative tools (e.g., manual property position setters) or when not to use it, so it stops short of a 5.

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

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

Annotations already indicate destructiveHint=true, but the description adds valuable context: it exports to DSN and imports routed SES, which could overwrite the board, and explains the best-of-N scoring mechanism including the 50,000-point bonus for targetNets. It lacks explicit warning about destructive effects, but the workflow disclosure and scoring details go beyond the annotations without contradicting them.

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 substantial but well-organized and front-loaded with the core behavior. Every sentence earns its place: the workflow, the prerequisite, the best-of-N behavior, and scoring details. Slightly long but appropriate for the tool's complexity.

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?

The tool is complex (export, run external CLI, import, best-of-N mode) and the description covers the key aspects: prerequisites, workflow, mode behavior, scoring, and parameter interactions. An output schema exists but isn't shown here, so the description doesn't need to explain return values. For this complexity, the description is complete enough for an agent to invoke it correctly.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds meaningful context beyond the schema: it explains how attempts > 1 changes behavior (best-of-N), how maxPasses is ignored when attempts > 1 in favor of passSchedule, and clarifies the scoring formula. These cross-parameter interactions and the recommended attempts range are only in the description.

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 ('Run Freerouting autorouter') and resource ('current PCB'), and details the full workflow: export to Specctra DSN, run Freerouting CLI, import routed SES. It clearly distinguishes itself from related tools like check_freerouting and import_ses by explaining the end-to-end process.

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 explicit context: requires Java 11+ and freerouting.jar (referencing check_freerouting). It also explains when to use different modes: set attempts > 1 for best-of-N, recommends 3–5 for dense boards, and notes single-attempt behavior is unchanged when attempts is omitted. This provides clear situational 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?

The annotations already provide destructiveHint=true and idempotentHint=false, and the description adds meaningful behavioral context: the sequence of operations (place then connect) and the effect of labelType on all nets wired in this call. This goes beyond the annotations and clarifies the tool's side effects without contradicting the destructive hint.

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 three sentences, front-loaded with the core purpose, and every sentence contributes essential information (combined action, relationship to sibling tools, operational order, labelType behavior). No filler or redundancy.

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 moderately complex combined operation, the description covers the main behavioral contract, references sibling tools for parameter defaults, and notes labelType's scope. The output schema exists, so return values are not needed. However, it omits any mention of origin_x/origin_y (which are also undocumented in the schema), leaving a small but noticeable gap in completeness.

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 60%, with missing descriptions for origin_x and origin_y. The description compensates by explaining the components object's structure ('Each component is like batch_add_components plus an optional nets map {pin: netName}') and elaborating on labelType's enum semantics. This adds meaningful value beyond the schema, though the placement origin parameters remain undocumented.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Place multiple components AND wire their nets in a single call' — a specific verb and resource. It also explicitly distinguishes it from related sibling tools by mentioning 'Each component is like batch_add_components plus an optional nets map' and contrasts it with 'batch_connect', making it unambiguous when this combined operation is intended.

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 clear context: it is the 'fewest-round-trip way to build a subcircuit' and explains the internal order ('Components are placed first, then nets are connected via batch_connect'). While it doesn't explicitly say 'use batch_add_components alone if you don't need nets', the combined nature and reference to the alternative imply the right usage. A brief exclusion would make it perfect.

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

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

The description discloses extra behavioral details beyond annotations: auto-positioning of reference/value fields (with override option) and the return payload structure. Annotations already mark the operation as destructive, so the description adds context without contradicting them.

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 three sentences, front-loaded with the main purpose and efficient in conveying parameter format and return values. No redundant phrases.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description appropriately focuses on usage context and parameter semantics. It covers the core behavior and return expectations. Minor omissions like error handling or atomicity are not necessary given the annotations and 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?

While the schema covers all parameters with descriptions, the tool description goes further by giving a concrete structure example for the components array and explaining the effect of auto_position_fields. This clarifies optionality and data hierarchy better than the schema alone.

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 uses a specific verb 'Add' and identifies the resource 'components to a schematic'. It also distinguishes from the sibling add_schematic_component by noting 'far fewer round-trips', making the tool's purpose unmistakable.

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 when to use by contrasting batch vs single-component calls, explicitly referencing add_schematic_component for smaller operations. It does not provide explicit exclusions or alternatives beyond that, 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 indicate destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds that it 'silence[s] ERC' and clarifies the data structure, but does not disclose potential side effects like overwriting existing flags or failing on invalid pins. This meets the baseline but offers limited extra behavioral insight.

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 two sentences, front-loaded with the core action and purpose, followed by a clarifying parameter note. No redundancy, filler, or unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations covering safety semantics, an output schema present, and 100% parameter schema coverage, the description is mostly sufficient. However, it does not address idempotency or failure behavior (e.g., what happens if a pin already has a no-connect flag), which would be useful but not essential for a simple batch operation.

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% for both parameters. The description's mention of 'pins' being a list of {componentRef, pinName} merely restates the schema definition without adding new meaning. Thus the baseline score 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?

The description clearly states the tool's action: 'Add no-connect (X) flags to multiple pins in one call'. It specifies the resource (pins), the purpose ('mark intentionally unconnected pins and silence ERC'), and distinguishes itself from the singular 'add_no_connect' sibling by emphasizing batch operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: when you need to mark multiple pins as no-connect to silence ERC. It implies batch usage but does not explicitly exclude the singular 'add_no_connect' or other 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?

Beyond the destructiveHint annotation, the description discloses several behavioral traits: replace=true clears existing labels, local labels may draw a wire instead of a duplicate when a facing label is nearby, global labels are placed one-per-pin, and it warns about power nets missing a PWR_FLAG. This is rich behavioral detail not present in 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?

The description is three sentences, front-loaded with the core purpose, then details. Every sentence provides essential behavioral or parameter information with no filler or redundancy.

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?

The tool is moderately complex with nested objects and multiple behaviors, and the description covers parameter format, label semantics, edge-case behavior (facing labels), and warnings. An output schema exists, so return values need not be explained. The description is complete for effective use.

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 value by clarifying that pin can be a number or name, explaining the meaning of labelType with practical guidance (global for power rails/sheet-spanning nets), and describing the effect of replace=true. This goes beyond the schema's field 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 opens with a specific verb+resource: 'Place net labels on multiple pins in one call to wire nets quickly.' This clearly states what the tool does and distinguishes it from single-label tools like add_schematic_net_label, emphasizing the batch aspect.

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 provides clear usage context: when to use local vs global labels ('for power rails and any net that spans sheets'), and implies batch use for wiring nets quickly. However, it does not explicitly name alternatives such as add_schematic_net_label or state when not to use this tool, stopping short of a 5.

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

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

Annotations already mark destructive and non-idempotent behavior. The description adds valuable context: each entry is applied individually via the single-component editor, and results are returned as per-reference updated/errors, implying partial failure semantics.

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 two sentences long, front-loaded with the primary action, and every part earns its place. The map structure explanation and return behavior are packed efficiently without redundancy.

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 an output schema present and annotations covering safety, the description is complete: it explains the batch nature, the structure of the components parameter, how each edit is applied, and what is returned. No critical gaps for a tool of this complexity.

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 descriptions cover both parameters, but the description goes further by giving a concrete map structure example ({reference: {value?, footprint?, newReference?, ...}}) and explaining how entries are applied. This enriches the abstract 'Map of reference -> fields to change'.

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 'Edit multiple existing components in one call' with a specific verb, resource, and scope. It clearly distinguishes from single-component editing and other batch operations like batch_move_components by focusing on property edits (value, footprint, reference) via a map.

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 use when multiple components need property edits in one operation, and clarifies that each entry goes through the single-component editor. It lacks explicit exclusions or alternatives (e.g., when to use batch_move_components), but the context is clear for most users.

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?

Despite strong annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds valuable behavioral context: it explains the coordinate system ('symbol-local coords, Y-up per KiCAD lib convention'), warns about the pre-rotation nature, and describes the body_bbox derivation (±1.27mm). It also details the compact mode behavior. No contradiction with 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?

The description is front-loaded with purpose, then provides usage guidance, output details, an important coordinate warning, and a compact-mode tip. Every sentence earns its place; there is no fluff or repetition. It is appropriately sized given the tool's complexity.

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?

The description is thorough: it explains the return content (pins, body_bbox), the coordinate frame, and when to use an alternative tool. Even though an output schema exists, the description adds necessary context about coordinate conventions that would not be obvious from the schema alone. The tool is well-contextualized among its siblings.

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 descriptions for all parameters, providing a solid baseline of 3. The description goes beyond this by giving concrete guidance for the 'compact' parameter: 'Set compact=true for simple 2-pin passives (Device:R/C/L) to get just pin_count, body_bbox, and is_symmetric.' This adds practical semantics not present in the schema.

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

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Return') and clearly states the resource and scope: 'pin names, numbers, types, and symbol-local coordinates for multiple symbols in a single call.' It also differentiates itself from the sibling 'list_symbol_pins' by instructing to use it 'instead of calling list_symbol_pins repeatedly,' making the purpose unmistakable.

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 explicit usage context: 'Use instead of calling list_symbol_pins repeatedly when placing a subcircuit — saves 5–10 round-trips.' It also specifies a clear alternative for post-placement coordinates: 'after placement use get_schematic_pin_locations for post-rotation schematic coordinates.' This goes beyond vague guidance and names exact 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?

Beyond the annotations, it discloses transactional rollback ('If one reference/spec is invalid, no components are moved') and the default save behavior. It does not describe all side effects, but given destructiveHint=true already signals modification, the added context is valuable.

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 with front-loaded purpose and no filler. Every sentence contributes behavioral or usage 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 tool with 3 parameters, a nested moves object, and an output schema, the description covers core behavior, rollback, and save defaults. It leaves dryRun to the schema description, which is acceptable given the schema richness.

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

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

Schema description coverage is 100%, so the schema carries most parameter meaning. The description adds context about reference/spec validity and save default but does not detail the placement spec format, which the schema already 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?

The description opens with 'Move multiple PCB components transactionally,' clearly specifying the verb, resource, and batch nature. It distinguishes from sibling move_component by emphasizing multiple components and all-or-nothing behavior.

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 conveys that this tool is for transactional multi-component moves, providing clear context for when to use it. It does not explicitly name single-component alternatives or list exclusions, so it stops short of a full 5.

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

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

Annotations already flag destructive/write behavior, but the description adds useful context: 'single file read/write' clarifies the operation's scope, and 'Returns per-item applied/failed lists' discloses partial-failure behavior. This goes beyond the annotations without contradicting them.

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 with no wasted words. The first sentence states purpose and comparative advantage; the second specifies input format and return behavior. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.