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

The description discloses that the zone is created unfilled and needs a separate fill step, which is an important behavioral nuance beyond the bare create operation. It also clarifies the optional pcb_path behavior, noting omission uses the configured default. The annotations are minimally informative with all false hints, so the description does meaningful extra work.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and the essential workflow hint, followed by a compact Args list. Every line earns its place and no wasted words exist. Given 10 parameters, the format is an efficient and scannable way to convey all necessary semantics.

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 10 parameters, 0% schema description coverage, and output schema not shown, the description successfully carries the full load by covering all parameters, the necessary fill_zones follow-up, and pcb_path behavior. However, it does not mention prerequisites like board existence or layer validity, nor does it describe potential error conditions, leaving a small but non-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 0%, but the description compensates by documenting every parameter with units, examples, defaults, and additional meaning. It explains thermal_relief as a boolean choice, priority as "higher fills first," corners as a polygon with min 3 points, and pcb_path as optional with a default configuration. This goes well beyond the schema's titles and defaults.

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

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

The description opens with a specific action-resource pairing, "Create an unfilled copper zone," and disambiguates it from sibling tools by clarifying that fill_zones must be called afterward. Names like add_keepout_zone and fill_zones are clearly distinct because the tool explicitly covers copper pours and defers filling.

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 when-to-use guidance by saying this creates zones and that "Call fill_zones afterward to compute the fills," establishing the expected sequencing. It does not explicitly contrast with add_keepout_zone or other zone tools, so it doesn't fully cover exclusions, but the core workflow is clearly stated.

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

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

Annotations already indicate this is a mutating (readOnlyHint=false) and non-destructive operation. The description adds meaningful context beyond annotations by explaining that the label is visible across all sheets and that schematic_path is optional with a default configuration. This is sufficient behavioral disclosure for a straightforward add operation.

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 concise and well-structured: a single purpose sentence followed by a clean args list. Every line adds value, and the parameter explanations are tightly written without unnecessary elaboration.

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 six parameters and three required, the description covers all parameter semantics, states the tool's global-label scope, and explains the optional schematic_path with its default behavior. Since an output schema exists, return-value details are not needed. The description is fully adequate for an agent to select and invoke this 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 description provides detailed, human-readable explanations for all six parameters, including the rotation degree mapping (0=right, 90=up, etc.), the valid shape enum values, and the optional behavior of schematic_path. This fully compensates for the 0% schema description coverage and adds clarity beyond the bare schema properties.

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 'Add a global net label' with a specific verb and resource, and adds the scoping detail 'visible across all sheets' that distinguishes it from local label tools like add_label or hierarchical labels. It is precise and not a tautology.

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 for cross-sheet net labels via the phrase 'global net label (visible across all sheets)', but it does not explicitly state when to use this tool versus alternatives such as add_label or add_hierarchical_label, nor does it mention exclusions. The guidance is implied rather than explicit.

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 this is a mutating operation (readOnlyHint=false), but the description adds minimal behavioral context beyond that. It mentions the name must match the parent sheet pin name, but does not disclose what happens on mismatch, whether the file is saved automatically, or other side effects. Given the annotations are present but not highly informative, the description carries some burden and partially fulfills it.

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 concise and well-structured, with a clear one-sentence purpose followed by a compact Args block. Every line provides necessary information (parameter name, explanation, or constraint) without extraneous prose. The front-loaded purpose makes it immediately scannable.

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 an output schema (so return values need not be described) and the parameters are fully explained, the description covers most operational context. However, it lacks mention of prerequisites such as the sub-sheet and parent sheet pin existing, and does not describe error behavior. These gaps are moderate given 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?

The input schema has no descriptions (0% coverage), so the description fully compensates by explaining each parameter: text must match a parent pin, shape is a direction with enumerated values, x/y are positions in mm, rotation is in degrees with allowed values, and schematic_path is optional. This adds substantial meaning beyond the bare 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 'Add a hierarchical label to a sub-sheet schematic,' using a specific verb and resource that distinguishes it from sibling tools like add_label and add_global_label. The phrase 'hierarchical label' and 'sub-sheet schematic' makes the tool's unique scope 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 this tool should be used: adding hierarchical labels to sub-sheet schematics. It also includes a critical usage constraint: 'Label name (must match parent sheet pin name).' It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to differentiate from similar tools.

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

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

Annotations are largely uninformative (all hints false). The description does add behavioral context by stating it 'Creates the sheet block in the parent and corresponding hierarchical labels in the child schematic,' which reveals the two files that are modified. However, it doesn't disclose what happens on partial failures, whether it overwrites existing labels, or other edge-case behaviors.

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 compact: two introductory sentences followed by a structured Args list. There is no filler or redundancy. Every sentence and item in the Args list contributes essential information, making it easy to scan and parse.

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

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

The description covers prerequisites, all parameters, and the core side effects of the operation. The presence of an output schema means return value details are not needed. It lacks discussion of edge cases such as duplicate labels or invalid states, but for a tool with 7 parameters and clear prerequisites, 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?

The description includes a full Args list that explains all 7 parameters, including the meaning of each and the direction allowed values (input, output, bidirectional, tri_state, passive). Since the schema provides 0% description coverage, the description is the sole source of parameter semantics and covers them thoroughly.

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

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

The description opens with a specific action: 'Add a hierarchical sheet to a parent schematic with matching labels in the child.' It clearly identifies the resource (schematic hierarchy) and the verb (add), and the detail about creating matching labels distinguishes it from related tools like add_hierarchical_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?

The description explicitly states a key prerequisite: 'The child schematic must already exist (create it with create_schematic first).' This gives clear context for when to use the tool. It doesn't explicitly contrast with alternatives, but the combination of hierarchical sheet plus label creation makes the intended use obvious.

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 that the call is atomic (one bad point refuses everything and nothing is written), that an existing junction is not duplicated but a wire through it is still split, and that the result itemizes written/existing/split junctions. These are exactly the behavioral traits an agent cannot infer from readOnlyHint=false and destructiveHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with purpose and the atomic-failure rule, and nearly every sentence earns its place by describing junction validity and side effects. The source-code citation ('sch_drawing_tools.cpp: 1465-1497 at 9.0.8') and the verbatim error string are somewhat noisy, and the Args block slightly restates the schema.

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

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

For a two-parameter write tool with annotations and an output schema present, the description covers prerequisites (valid junction topology), atomicity, idempotency-like behavior, and what gets modified, so an agent has everything needed to call it correctly without inspecting source.

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 0%, so the description must carry parameter meaning, and it does: it defines the point dict keys (x, y) and explains that schematic_path is a .kicad_sch path that is optional and falls back to a configured default. It adds real meaning beyond the bare schema, though it could say more about coordinate units/reference frame.

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

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

The opening sentence states a precise verb and resource ('Add multiple junctions') and even anchors it to KiCad's native junction tool, so the purpose is unmistakable. It never names a sibling (remove_junction, list_schematic_junctions) to delimit the add/remove/list space explicitly, which is the only thing keeping it off a 5.

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

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

The description gives strong when/when-not guidance by enumerating valid topologies (crossing, T, wire end at a pin) and invalid ones (empty space, straight-wire interior, L corner, wire ending at a pin), plus the editor's refusal. It stops short of pointing to an alternative tool (e.g., connect_pins or wire_pins_to_net) for the cases this tool rejects, so it is clear context without explicit alternatives.

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

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

Annotations provide no hints (all false), so the description carries the burden. It discloses the zone's restriction capabilities and default layers, and notes that pcb_path is optional. However, it does not mention side effects such as direct file modification, whether the zone is appended to existing zones, or any validation/error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by a compact, scannable argument list. No filler or repetition; every line provides necessary 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?

While the description thoroughly covers parameter semantics, it lacks key contextual details for a mutating tool: no mention of file modification side effects, no guidance on when to use vs sibling zone tools, and no reference to expected return values (though the output schema exists). This is adequate but leaves clear gaps.

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

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

Schema description coverage is 0%, so the description effectively compensates by explaining every parameter: corners as {x,y} dicts with min 3, layer defaults, each no_* boolean's meaning, and pcb_path optionality. This adds significant meaning beyond the bare 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 'Create a keep-out zone that restricts placement of specified items,' which is a specific verb+resource statement that clearly defines the tool's function. This also distinguishes it from siblings like add_copper_zone, which serves a different 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?

The description implies usage through its purpose statement, but it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites. For example, it does not contrast with add_copper_zone or explain when a keep-out zone is preferable to other restrictions.

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 a write operation (readOnlyHint=false), and the description aligns by saying 'Add'. It adds some context for rotation values but does not disclose other behavioral traits like file-modification side effects or error conditions. With annotations covering the basic safety profile, this is adequate but not rich.

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 concise and well-structured: one sentence for purpose, then a clear Args list. Every line adds value, and it is appropriately sized for a five-parameter tool.

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, the description fully covers parameter semantics, optionality, and coordinate conventions. An output schema exists, so return value explanation is unnecessary. No prerequisites or complex behaviors are 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?

The input schema has zero parameter descriptions, so the description carries full burden. It explains text with examples, defines rotation degrees, and clarifies that schematic_path is optional. This is exactly the kind of semantic enrichment needed for correct invocation.

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 resource ('net label') with positional context, clearly distinguishing it from sibling tools like add_global_label or add_hierarchical_label. It is unambiguous and precisely states the action.

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 explicit guidance on when to use this tool versus alternatives such as add_global_label or add_text. Usage is implied by the tool's name and description, but there is no direct comparison or exclusion, leaving the agent to infer context.

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

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

The description states symbol_lib_path is optional, but the schema marks it as required, a direct contradiction that undermines agent correctness. Additionally, with all annotations false, the description carries the full burden for disclosing side effects, but it neither explains the mutation behavior nor mentions idempotency or error handling.

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 concise, uses a clear docstring structure with an Args block, front-loads the purpose, and avoids redundancy. The only blemish is the optionality error, but that is a content issue, not a structural one.

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

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

For a mutation tool with no annotation support and incomplete parameter documentation, the description should clarify the exact behavioral outcome (e.g., whether the symbol is added to the schematic library vs. instantiated) and highlight the required/optional mismatch. It does not.

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?

Since schema description coverage is 0%, the description compensates by explaining each parameter with a format hint (e.g., '.kicad_sym' and '.kicad_sch') and an example for symbol_name. However, the incorrect 'optional' label for symbol_lib_path reduces its value.

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 'Load' with a clear resource ('a symbol definition from a .kicad_sym library') and destination ('into the schematic'), distinguishing it from siblings like add_symbol or place_component.

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 does not mention when to use this tool over alternatives like add_symbol or place_component, nor does it provide any exclusions or prerequisites. The 'into the schematic' context is implied but no explicit guidance is given.

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 provide no hints (all false), so the description bears the full burden. It states it adds a line but does not mention side effects, coordinate units/origin, file modification behavior, or reversibility. Only the optional pcb_path is noted, which is insufficient for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single purpose sentence followed by a compact parameter list. Every line adds value, no fluff, and the structure front-loads the core action before parameter details.

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

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

All 7 parameters are described with defaults and optionality noted. Missing details like coordinate units and preconditions are minor for a simple geometry-add tool. The output schema handles return values, so no description needed there. Overall, adequate 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 0%, so the Args section in the description is crucial. It explains start/end coordinates, gives layer examples, states width units (mm), and clarifies pcb_path optionality. However, it omits units for x/y coordinates and the origin reference, preventing a perfect 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 begins with a clear verb-object statement: 'Add a graphic line to the PCB', followed by examples of layer usage (edge cuts, silkscreen). This distinguishes it from sibling tools like add_trace (electrical) and add_pcb_text, giving a specific resource and scope.

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 for graphic lines via examples but does not explicitly contrast with electrical trace tools or state when not to use it. It gives context but lacks explicit exclusions or alternative recommendations.

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 are all false, so they provide no safety or side-effect information, leaving the description to carry the full disclosure burden. The description explains the pcb_path default behavior but does not mention mutation scope, error handling, file modifications, or return values. For a mutating tool, this is a significant transparency 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 compact and well-structured: a one-line summary followed by an Args list. Each line adds concrete value without redundancy or unnecessary fluff, keeping it easy for an agent to parse.

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

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

With six parameters and annotations that provide no supporting context, the description covers all parameter semantics and the core action. It does not mention coordinate units or return behavior, but the existence of an output schema (if populated) would likely address return expectations. Overall, it is adequately complete for a PCB text-addition 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 0%, so the description is the primary source of parameter meaning. It explains each parameter, provides concrete layer examples ('F.SilkS', 'B.SilkS', 'F.Fab'), and clarifies pcb_path optionality with a default behavior. This strongly compensates for the bare schema, though some details like coordinate units are absent.

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 text to a PCB with specific layers (silkscreen, fab, etc.). The verb 'Add' and resource 'the PCB' make the purpose unambiguous, and it immediately distinguishes from the schematic-oriented add_text sibling by naming PCB layers.

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 context by mentioning 'silkscreen, fab layer, etc.' and the PCB scope, but it does not explicitly guide when to choose this tool over alternatives like add_text or add_pcb_line. It gives enough context to infer when to use it, though without explicit exclusions or direct sibling comparisons.

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

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

Annotations already declare non-readOnly, non-destructive, non-idempotent. The description adds real behavioral context beyond that: the internal delegation to place_component, the isPower=True nature of the symbols, and the ERC semantics of PWR_FLAG (tells ERC the net has a source it cannot see). It does not discuss repeat-call behavior despite idempotentHint=false, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose, then mechanism, then the PWR_FLAG note, then a structured Args block. Every sentence conveys useful information, though the PWR_FLAG paragraph is slightly tangential to the core placement action. Well organized and appropriately sized for an 8-parameter tool.

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, return values need not be described. For an 8-parameter placement tool the description covers purpose, mechanism, ERC-related behavior, and every parameter including optional/default semantics. It is essentially complete, missing only explicit sibling routing guidance.

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 0%, so the description carries the full burden, and it delivers a complete Args section explaining all 8 parameters: lib_id with concrete examples, reference format '#PWR01', rotation in degrees, symbol_lib_path for out-of-stock libraries with default behavior, schematic_path default, and project_path purpose. This fully compensates for the empty schema titles.

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

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

States a specific verb and resource ('Place a power symbol') with examples (VCC, GND, +3V3), and clarifies the mechanism by noting it uses place_component internally and that these are regular 'power' library symbols with isPower=True, which helps distinguish it from generic symbol placement. It does not explicitly contrast against add_symbol or place_component for the main use case, so differentiation is good but not complete.

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 domain guidance on the PWR_FLAG companion case and clarifies 'Places only the symbol asked for', but gives no explicit when-to-use-this-vs-siblings rule (e.g., versus place_component or add_symbol). Usage is implied rather than stated, so the minimum-viable 3 fits.

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 a mutating operation (readOnlyHint false) but not destructive, which is consistent. The description adds constraints like pin name matching and optional schematic_path, but does not disclose side effects on the child schematic or failure behavior. Some transparency is provided, but not deep.

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 concise docstring with a clear opening purpose sentence and an Args block. No wasted words, though it is structured more like a code docstring than prose, which is appropriate for the format.

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 all parameters explained, the description covers essential context for using the tool. It lacks examples or error conditions, but for a straightforward parameterized 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?

All 5 parameters are explained in the description, including allowed values for connection_type and side, and the optional nature of schematic_path. Since schema descriptions are empty (0% coverage), this description fully compensates and adds significant meaning beyond the schema.

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

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

The description clearly states the action ('Add a pin') and the resource ('existing hierarchical sheet block'), making the tool's purpose immediately obvious. It distinguishes itself from siblings like remove_sheet_pin and is specific about what the pin is added to.

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 'existing hierarchical sheet block' implies the sheet must already exist, and the note about matching a hierarchical label provides context. However, there is no explicit when-to-use vs alternatives or exclusions, leaving usage guidance implied rather than stated.

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

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

Annotations indicate readOnly=false and destructive=false, which align with an add operation. The description adds useful behavioral context (auto-creating the library file, auto-computing rectangles when omitted). However, it fails to disclose behavior when a symbol with the same name already exists (overwrite vs error), a significant gap for a mutating tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose statement followed by an organized Args list. Each parameter gets a line with defaults in parentheses. Every sentence contributes value, and the length is proportional to the tool's complexity (11 parameters).

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 tool's purpose, library file creation, automatic rectangle computation, and all parameter details. It lacks discussion of duplicate symbol names and error handling, but given the existence of an output schema and annotation context, the description is largely complete and only missing these edge-case behaviors.

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 0%, so the description carries the full burden of parameter documentation. It thoroughly explains every parameter, including pin types, defaults (e.g., length 2.54, rotation 90/180/270), and the semantics of rectangles. This goes far beyond the schema's bare titles and defaults.

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 'Add a new symbol definition to a .kicad_sym library' and explains it creates a complete symbol with pins and body graphics, which is a specific verb+resource. However, it does not explicitly distinguish itself from the sibling tool 'add_lib_symbol', so it falls short of fully differentiating among siblings.

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: this tool is used to add a new symbol definition, and it will create the library file if missing, implying when it might be used. However, it gives no explicit guidance on when to prefer it over alternatives like add_lib_symbol or create_symbol_library, nor any exclusion 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?

The annotations indicate this is a non-read-only, non-idempotent mutation, but the description adds no extra behavioral context. It doesn't disclose whether it modifies the file in-place, creates duplicates, or requires an open schematic, leaving the agent without important side-effect information.

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 compact, front-loaded with the core action, and uses a clear Args list. 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 simple add operation, the description covers the primary purpose and parameter meanings. However, it lacks behavioral side effects, error handling, or prerequisites, and the presence of an output schema doesn't replace the need for this context. It's minimally viable but not fully complete.

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

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

With 0% schema description coverage, the description's Args section is essential. It explains text content, x/y position, rotation in degrees, and the optional schematic_path with its default behavior. This compensates well for the schema gap, though it omits coordinate units/origin specifics.

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 'Add a text annotation to the schematic' with a specific verb and resource, clearly identifying the action. However, it doesn't differentiate from similar sibling tools like add_label or add_global_label, leaving potential ambiguity for the agent.

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 such as add_label, add_global_label, or add_pcb_text. The description only states the action, not the context or exclusion criteria.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the rows*cols <= 256 grid limit, automatic net detection from the pad when net_name is None, and the pad auto-selection rule. It does not discuss whether existing vias are replaced or how the mutation interacts with the board, but it materially exceeds the annotation baseline.

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 one-line summary is front-loaded and the Args list is justified given zero schema documentation. Every line adds information an agent needs; the only minor cost is length, but nothing is redundant.

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

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

For a 9-parameter mutation tool with 0% schema coverage, the description documents all parameters, their units, defaults, and constraints, and an output schema exists so return values need no explanation. An agent has everything required to call it correctly.

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

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

Schema description coverage is 0% across 9 parameters, so the description carries the full burden and does so: it defines meaning and units for spacing/via_size/via_drill (mm), documents defaults semantics for pad_number ('empty auto-selects largest SMD pad'), net_name (None = auto-detect), pcb_path (omit = default), and states the rows/cols constraints and minimums.

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

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

States a specific verb and resource ('Add a grid of thermal vias') with scope ('under a footprint pad'), which separates it cleanly from the sibling add_via (single via) and add_copper_zone. An agent can identify the operation without opening the schema.

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

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

Usage is implied by the phrasing 'under a footprint pad', and the pad_number arg says it auto-selects the largest SMD pad when empty. However, there is no explicit when-to-use / when-not-to-use guidance against alternatives such as add_via or add_copper_zone, so the agent must infer routing.

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

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

Annotations already declare the write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), lowering the bar. The description adds genuinely useful behavior: the pcb_path default-file fallback and the net=0 encoding quirk with a source citation. It still omits key traits such as whether the edit is persisted to disk immediately, how invalid layer/net values are handled, and whether coordinates are in mm.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose sentence is front-loaded and the per-argument list is compact and scannable. The parenthetical source-code reference (pcb_io_kicad_sexpr.cpp:2860-2861 at 10.0.7) is borderline noise but does substantiate the net=0 claim, so it mostly 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. All eight parameters are documented with units, examples, defaults, and the net encoding edge case — enough for an agent to call this correctly. Only the coordinate unit is left implicit.

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

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

Schema description coverage is 0% (properties carry only titles), so the bulk of parameter meaning comes from the description — and it delivers: width in mm, layer examples ('F.Cu', 'B.Cu'), net numbering semantics with the 0 = no-net rule, and pcb_path optionality. It does not state the unit for x1/y1/x2/y2 or constraints on width, so it stops short of full 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 gives a specific verb+resource: 'Add a trace segment between two points.' An agent immediately knows this creates a PCB copper trace. However, it never distinguishes itself from siblings like add_via, add_pcb_line, autoroute_pcb, or set_trace_width, so the differentiation burden falls entirely on the name.

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

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

There is no when-to-use guidance, no prerequisites (e.g. board must be loaded, layer must exist), and no mention of alternatives such as autoroute_pcb or set_trace_width for changing an existing trace's width. The agent must infer context from the tool name alone.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the non-obvious net=0 behavior and file-format detail, but says nothing about what actually changes on disk, whether the board must be saved afterward, or failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence, followed by a clean Args list. It is appropriately sized, though the parenthetical source-code citation '(pcb_io_kicad_sexpr.cpp:2860-2861 at 10.0.7)' is extraneous detail that does not help an agent invoke the tool.

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 an output schema and annotations that already declare the safety profile, the description is nearly complete: all parameters are documented and defaults/nuances are surfaced. The one missing piece is guidance on when to choose this single-via tool over add_thermal_vias or other board-modifying 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 description coverage is 0%, so the description carries the full burden and does so: every one of the seven parameters is explained, including units (mm) for size/drill, the precise meaning of net=0, layer defaults, and pcb_path semantics. The only minor gap is that x/y units and coordinate origin are not stated, but overall it meaningfully compensates for the empty schema.

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

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

States a specific verb and resource: 'Add a via at a position.' An agent can distinguish it from most siblings (add_trace, add_pcb_text, etc.), but it never differentiates itself from the closely related add_thermal_vias tool. That missing sibling distinction keeps it at a 4 rather than a 5.

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

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

No when-to-use guidance, no prerequisites (e.g., must a board be open or a net exist?), and no mention of alternatives such as add_thermal_vias or add_trace. The description provides argument semantics but leaves usage context entirely to inference.

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

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

Far exceeds the annotations: it discloses that junctions are auto-created at 3+ wire directions/pins, that existing wires are only split and the call is refused with nothing written when KiCad's trim would cut an existing wire (atomicity), that zero-length wires are dropped, and that merging across a two-pin part never shorts it. It also states the result reports junctions/splits/left-out/trimmed stretches and that no-op calls write nothing.

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?

Purpose is front-loaded in the first sentence, but the behavioral paragraph is a dense run-on that includes low-value implementation trivia (source file, line numbers, version 9.0.8). Much of it earns its place, yet it could be cut substantially without losing agent-relevant information.

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

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

An output schema exists, so return values need not be spelled out, yet the description still summarizes what the result counts. Combined with the mutation/refusal semantics it covers the operation well; the main residual gap is coordinate units and the absence of guidance relative to sibling wire tools.

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

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

Schema description coverage is 0%, so the description must carry the load. It restates the WireSpec keys and usefully clarifies that schematic_path is optional and falls back to the configured default (which the schema's empty-string default does not convey), but it never states coordinate units or origin for x1/y1/x2/y2 — a meaningful gap for a geometry tool.

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

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

States a specific verb and resource ("Add multiple wires at once") and clarifies it mirrors KiCad's own wire tool, which separates it from PCB-side siblings like add_trace. It does not explicitly distinguish itself from close schematic siblings such as connect_pins, wire_pins_to_net, or add_junctions, leaving some ambiguity for an agent choosing among wire-creation 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?

Usage is implied rather than stated: batch-drawing wire segments on a schematic, with junctions handled automatically (hinting you need not call add_junctions). There is no explicit when-to-use versus when-not, and no named alternative such as connect_pins or wire_pins_to_net despite those being obvious siblings.

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

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

With no annotations indicating safety or idempotency, the description must disclose behavior itself. It does so by explaining that it assigns sequential numbers, respects existing references, and scans the hierarchy when project_path is given. It could be more transparent about file modification or reversibility, but the provided details are substantive.

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 tight: a one-sentence summary, a short explanatory paragraph, and an explicit Args list. No filler words. Every sentence contributes to understanding what the tool does and how to use it.

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

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

For a two-parameter tool, the description covers the essential behavior, parameters, and hierarchy nuance. An output schema exists, so return value details are not required. It doesn't address edge cases like partially annotated boards or error scenarios, but given the tool's simplicity, the description is largely complete.

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

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

The input schema has no descriptions for the two parameters, so the description must compensate. It explains both schematic_path and project_path concisely, including their optionality and the effect of omitting them (using configured default, scanning hierarchy). This adds meaning beyond the schema's bare names and defaults.

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: 'Auto-assign reference designators to unannotated components.' This clearly states the tool's core function and distinguishes it from sibling tools like remove_component or add_wires. The additional detail about finding '?' in references further pins down the exact use case.

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 tells you when to use this tool: when components have '?' in their reference designators. It also explains hierarchical behavior when project_path is provided. However, it does not explicitly name alternatives or exclusion criteria, so it stops short of full usage 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 declare non-readOnly, non-idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the exact side effects created (stub wires plus net labels), the pin-to-net mapping, and the default-resolution behavior of the optional path args (omit to use the stock library named by the lib_id prefix, omit to use the configured default schematic).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded summary followed by a mechanics sentence and an Args block; the ordering is sensible and every line is informative. The opening line and the second sentence overlap slightly (both say it places the cap and wires it), which is minor redundancy but not waste.

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

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

An output schema exists so return values need no explanation, and all 11 parameters are covered, including the tricky optional-path semantics. Remaining gaps are the lack of alternative-tool routing and any warning that the operation is non-idempotent (re-running would create duplicate symbols/wires).

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 0%, so the description carries the full burden, and it does: every one of the 11 parameters is documented with a concrete example (lib_id "Device:C", reference "C5", value "100nF", power_net "VCC"/"+3V3", ground_net "GND"/"PGND") plus stated defaults and the semantics of the three optional path arguments.

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

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

States a specific compound action (place a decoupling cap AND wire it to power/ground nets) with concrete mechanics — pin 1 to power_net, pin 2 to ground_net via stub wires and labels. This clearly distinguishes it from the generic siblings place_component, add_symbol, connect_pins, and wire_pins_to_net.

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 mechanics imply when this tool is preferable (a one-shot decoupling-cap placement) but it never says so explicitly and never names an alternative path such as place_component + connect_pins. No when-not guidance, no prerequisites (e.g. schematic must exist), so the routing decision is left to inference.

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

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

The description discloses key behavioral traits beyond the annotations: it explicitly states the original board is never modified (important given readOnlyHint=false), mentions the auto-download of the Freerouting JAR (~20MB) on first run, and warns about the multi-threaded routing issue. This adds significant context about side effects and requirements that the annotations alone do not provide.

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 well-structured and front-loaded: the first sentence states the core purpose, followed by a concise workflow summary, then prerequisites, and finally parameter details. Every sentence adds value, and the warning about num_threads is particularly useful. It's appropriately sized 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?

Given the tool's complexity (5 parameters, external dependencies, side effects), the description is remarkably complete. It covers the workflow, prerequisites, side effects (auto-download, no modification of original), parameter semantics, and even includes a warning about known issues. The output schema exists, so return values don't need explanation. This is a model description for a complex 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 schema has 0% description coverage, so the description must compensate. It does: it explains pcb_path (optional, default), max_passes (optimization passes), num_threads (with detailed warning), timeout (max seconds), and output_dir (default behavior). This adds meaning beyond the schema's basic type/default information, though it could be slightly more explicit about the exact format of pcb_path and output_dir.

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: 'Autoroute PCB traces using the Freerouting autorouter.' It specifies the verb (autoroute), the resource (PCB traces), and the method (Freerouting). It also distinguishes itself from sibling tools like add_trace or remove_traces by describing the full automated routing workflow.

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: it explains the workflow (exports to DSN, runs Freerouting, imports results), states that the original board is never modified, and lists prerequisites (Java 17+, matching pcbnew bindings). It also gives specific advice on num_threads, warning about known issues and recommending DRC checks. This clearly helps the agent decide when and how to use the 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?

Annotations already declare readOnly/idempotent/non-destructive, yet the description goes well beyond them: checks operate on the origin, not the courtyard, so body overlaps can still report ok; no rotation parameter exists because rotating about the origin cannot change the answer; and keep-out reading semantics (layer expansion, KiCad's own-keepout exclusion) are spelled out. That is genuine behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, followed by rationale caveats and then Args. Efficient overall, though the embedded source citation (pcbnew/pcbexpr_functions.cpp:697 at 9.0.8) is closer to implementation trivia than agent-usable 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 present, return-value explanation is unnecessary, and the description covers the subtle semantics an agent needs (origin-based checks, no rotation, keep-out interpretation) plus every parameter. Nothing required to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry the params, and it does via an Args block covering all four: reference designator, proposed x/y, and optional pcb_path that falls back to the configured default. It does not state units for x/y (presumably mm), which is the only meaningful gap.

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

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

States a specific verb (check) and resource (placing/moving a footprint to x,y) plus the outcome being evaluated (constraint violation). An agent can immediately distinguish this simulation/pre-flight check from the sibling move_footprint, which actually mutates placement.

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

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

Usage is implied rather than stated: it's clearly a pre-flight query, but the description never says 'use before move_footprint' nor names any exclusion or alternative. The caveats about origin-point checking and no rotation parameter give useful framing but are not routing guidance.

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

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

Annotations only declare it is a non-readonly, non-idempotent, non-destructive mutation. The description goes well beyond that, disclosing that junctions are created at meeting points, that existing wires are split there (citing KiCad behavior), and that the result names each junction and split. It stops short of stating reversibility or permission requirements.

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?

Purpose is front-loaded in a clear first sentence, but the junction paragraph is dense and cluttered with source-file line citations (sch_line_wire_bus_tool.cpp:1263-1267) that consume space without helping the agent invoke the tool. The Args block is clean and useful.

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?

Output schema exists, so return-value explanation is unnecessary, and the description still notes that junction/split names are produced. For a mutation tool it communicates the key side effects, though it omits whether junction insertion can be suppressed and how failures are reported.

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 0%, so the description must carry the burden, and it largely does: it documents all five args including examples ('U1', 'C3') and the fact that schematic_path is optional with a configured default. It leaves pin name-vs-number format and path format slightly ambiguous, but compensates adequately.

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

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

States a specific verb (connect), resource (two component pins), and the routing strategy (Manhattan / L-shaped). It also clarifies the tool's abstraction level by saying it bundles get_pin_positions + coordinate math + add_wires, so an agent can distinguish it from the low-level add_wires 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?

The 'combines X + Y + Z into one call' framing implies when to prefer this over manually chaining the three lower-level tools, which is useful. However, it never names or contrasts with close siblings like wire_pins_to_net or add_wires, and gives no when-not conditions or prerequisites.

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

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

Annotations already indicate the tool is not read-only (mutation). The description adds that the directory is created if missing and specifies the exact files created, providing 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?

The description is short and to the point, with two clear sentences and a simple argument list. It could be slightly more structured (e.g., numbered steps or clarification of return), but it is not verbose.

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 that an output schema exists, the description does not need to detail return values. It covers the core action, files created, and parameter roles, making it sufficiently complete for a project creation 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 description adds some meaning to parameters: 'directory' can be created if missing, and 'name' is used for filenames. However, with 0% schema coverage, the description should offer more detail, such as naming conventions or path restrictions.

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'), the resource ('a KiCad 9 project'), and the specific file types generated (.kicad_pro, .kicad_prl, .kicad_sch). It differentiates from sibling tools like 'create_schematic' which create only schematic files.

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 is used to start a new project, but it does not provide explicit guidance on when to use it versus alternatives (e.g., before creating schematics), nor does it mention prerequisites or exclusions.

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

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

The description does not disclose behaviors beyond the annotations, such as whether the tool overwrites an existing file, requires parent directories, or returns a success/failure status. More critically, it states the schematic_path is 'Optional' while the input schema marks it as 'required', creating a misleading contradiction that could cause incorrect invocation.

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 concise, consisting of two sentences. It front-loads the primary purpose and then structures the parameter explanation clearly under 'Args'. No unnecessary words or restatements.

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 file-creation tool, the description lacks critical context: it does not mention what happens if the file already exists, whether directories are auto-created, or what the tool returns. The contradictory 'Optional' claim further undermines completeness, leaving the agent with insufficient guidance for correct usage.

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 description adds semantic meaning by explaining that the parameter is a file path and that there is a configured default. However, since schema coverage is 0%, this is the only source of param info, and it contains an inaccurate statement about the parameter being optional, which reduces its reliability.

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'), a specific resource ('a valid empty KiCad 9 schematic file'), and the file extension (.kicad_sch). This unambiguously distinguishes it from sibling tools like create_project, which creates a project rather than a schematic.

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. It does not mention prerequisites, typical use cases, or exclusions. The only contextual hint is the parameter description, but there is no explicit 'when to use' or 'when not to use' information.

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 offer minimal safety hints (all false), so the description carries some responsibility. It adds context about the optional path and default behavior, but does not disclose what happens if the file already exists, whether it overwrites, or any error conditions. This is moderate beyond the schema but lacks depth.

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 exceptionally concise: two short sentences deliver the purpose and the parameter semantics. It front-loads the key action and avoids unnecessary detail, making it easy to parse quickly.

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

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

The tool is simple with one parameter, and the description covers the core purpose and parameter meaning. However, it omits details about the configured default path and behaviors for existing files. The output schema likely covers return values, so the description is largely complete but leaves minor edge cases unspecified.

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 description coverage is 0%, so the description must compensate. It does add meaning by stating the path is for a .kicad_sym file and that it is optional, but this directly contradicts the schema which marks symbol_lib_path as required. This conflicting guidance undermines semantic clarity and could mislead an agent.

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 creates a valid empty KiCad 9 symbol library, specifying both the action (create) and the resource (library). This distinguishes it from sibling tools like create_schematic or add_lib_symbol, which have different purposes.

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 such as create_sym_lib_table or add_lib_symbol. It does not mention prerequisites, typical workflows, or situations where another tool would be more appropriate, leaving the agent to infer usage context.

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

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

The description discloses a key behavioral detail beyond the annotations: 'Overwrites existing sym-lib-table if present.' This adds specific context to the destructiveHint=true annotation, clarifying exactly what gets overwritten. This goes beyond the bare annotation and is valuable for the agent.

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 short and front-loaded, with the main action in the first sentence. The entry requirement and overwrite note are important, but the 'Args' block largely restates the schema, adding slight redundancy. Overall, each sentence contributes value, and the structure is clean.

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 file creation tool, the description covers the essential information: what it does, what the arguments are, the required entry structure, and the overwrite behavior. The output schema handles return details, and annotations cover the destructive nature. It doesn't mention directory existence or edge cases, but it is sufficiently complete for this scope.

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 0%, so the description must compensate. It does add a brief explanation for 'directory' (Directory to write sym-lib-table in) and repeats that entries need 'name' and 'uri' keys, but this largely duplicates the schema's required fields and type definitions. It doesn't provide deeper semantics like path constraints or URI formats, so the added value is minimal.

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: 'Create a sym-lib-table file in the given directory.' This is a specific verb and resource, and it distinguishes this tool from siblings like create_schematic or create_symbol_library by naming the exact file type. The overwrite note further clarifies scope.

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 explicit when-to-use guidance or alternatives. It does explain the required entry keys and directory argument, which is a form of usage guidance, but it doesn't say when to choose this tool over similar creation tools. No exclusions or alternative references are given.

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 destructiveHint=true, but the description adds little beyond 'copying the child file with new UUIDs.' It does not disclose what is destroyed (e.g., existing files overwritten), whether the parent schematic is modified, or what happens if the target file already exists. The description could mislead an agent into thinking the operation is purely additive.

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 compact and front-loaded. The first sentence states the core action, and the Args list is directly informative with no filler or repetition. Every line adds value.

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 basic operation and parameters, but for a destructive hierarchical operation it lacks important context: what files are affected, whether the new sheet is linked to the parent, and any preconditions. Although an output schema exists, the behavioral side-effects and prerequisites remain under-specified.

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

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

With 0% schema coverage, the description fully compensates by explaining every parameter. It clarifies optionality (schematic_path), purpose (project_path for hierarchy metadata), and default behavior (new_file_name auto-generated) in a concise manner, making each parameter meaningful beyond the schema's bare titles.

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: 'Duplicate a hierarchical sheet, copying the child file with new UUIDs.' This clearly distinguishes the tool from siblings like add_hierarchical_sheet (create new) or remove_hierarchical_sheet (delete), making the purpose obvious.

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 through its action ('duplicate') and parameters, but does not explicitly state when to prefer this over alternatives, nor does it mention exclusions or prerequisites. It lacks guidance such as 'instead of add_hierarchical_sheet' or 'only when needing a copy with new UUIDs.'

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 idempotent and non-destructive behavior, so the description's main addition is the conditional behavior of parameters (render fills dimensions, mesh formats leave them unset) and the default path behavior for pcb_path/output_dir. It does not disclose potential file overwriting or directory creation, but with annotations covering safety, the added context is adequate.

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 starts with a concise purpose statement, then a clarifying sentence about render vs mesh behavior, followed by an organized Args list. Every line adds information necessary for correct use, and the structure makes it easy to scan.

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

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

With 7 parameters, conditional dependencies, and no schema descriptions, the description addresses all required usage details: optional paths with defaults, format choices, and parameter applicability per format. The output schema is available so no return-value explanation is needed. The tool is fully specified 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 descriptions are absent (0% coverage), so the description carries full responsibility. It explains each of the 7 parameters, including enum values for format, defaults, and render-only constraints for width/height/side/quality. The note about 'render fills width, height and side; the mesh formats leave them unset' adds crucial conditional semantics 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 opens with 'Export PCB 3D model or render 3D view to image,' which is a specific verb+resource statement. It clearly distinguishes from sibling export tools like export_schematic or export_pcb by focusing on 3D output. The format enumeration (step, stl, glb, render) further clarifies scope.

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 that render uses width/height/side/quality while mesh formats ignore them, guiding parameter selection. However, it does not explicitly state when to choose this tool over other export tools, such as export_pcb or export_gerbers. The purpose is clear but no alternatives or exclusions are named.

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 provide idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds that it writes CSV and uses configured defaults, but it does not disclose details like output file naming, overwrite behavior, or behavior when the schematic path is invalid. It provides moderate value beyond 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 compact and well-structured: a one-sentence purpose followed by a concise Args block. Every sentence provides useful information, and there is no filler or repetition of obvious schema details.

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

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

For a simple, idempotent export tool with two optional parameters and an existing output schema, the description covers the essential inputs and defaults. It does not explain generated file naming or invalid-input behavior, but those are not necessary for selecting and invoking 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 input schema has 0% description coverage, but the tool description fully documents both parameters: schematic_path points to a .kicad_sch file, output_dir specifies the output location, and both are optional with configured fallback defaults. The description fully compensates for the schema's lack of parameter 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 uses a specific verb and resource: 'Export Bill of Materials (BOM) as CSV.' This clearly identifies the tool's output format and distinguishes it from sibling export tools like export_netlist, export_schematic, or export_pcb in the same family.

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 intended use—when a CSV BOM is needed—but it does not explicitly state when not to use it or mention alternatives. With many export-related sibling tools, some explicit differentiation would improve 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?

With annotations present (readOnlyHint=false, idempotentHint=true), the description adds useful context about accepted path types and the use of configured defaults. However, the inconsistency between the description claiming footprint_path is optional and the schema marking it required undermines behavioral clarity, and no mention is made of side effects like file creation beyond what the annotations imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and logically structured with an Args section. It avoids excessive verbosity, but the optionality error introduces a correctness issue that slightly detracts from the clarity of the structure.

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 relatively simple tool with an output schema and annotations, the description covers the core purpose and parameters. Yet it fails to clarify the required nature of footprint_path, omits file naming or overwrite behavior, and doesn't mention that it writes a file. The mismatch between description and schema is a significant 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?

The description provides additional meaning by specifying footprint_path accepts a .kicad_mod file or .pretty directory and output_dir is an output directory, which helps with a 0% schema description coverage. However, it incorrectly states footprint_path is optional when the schema designates it required, creating a dangerous contradiction that could cause the agent to omit a necessary 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 states the tool 'Export footprint to SVG' with a specific verb, resource (footprint), and output format. It distinguishes itself from the sibling tool export_symbol_svg by targeting footprints instead of symbols.

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 lacks explicit guidance on when to use this tool versus alternatives, offering no exclusions or preferred contexts. It misleadingly implies both arguments are optional, contradicting the schema that marks footprint_path as required, leaving the agent without reliable direction.

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 thoroughly discloses behavior beyond annotations: it explains the single-layer versus multi-layer output modes, what output fields are populated in each case, the default behavior when 'layers' is omitted, and that 'include_drill' is ignored in single-layer mode. It also notes that pcb_path and output_dir fall back to configured defaults. This is a model of transparency.

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 efficient and well-organized: a purpose sentence, a behavioral paragraph, then a bulleted Arg list. It packs a lot of information into a relatively small space, though the prose could be slightly more scannable with better use of formatting (e.g., bolding modes). For its length, it's highly effective.

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 file-export tool with all-optional parameters and a clear output schema, the description covers the essential behaviors: mode selection, defaults, and drill handling. Minor edge cases (e.g., behavior with invalid layer names) are not discussed, but these are reasonably outside the core use case and the output schema covers return values.

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?

Since schema description coverage is 0%, the description carries the full burden and does so excellently. It explains each parameter's meaning, defaults, and inter-relationships (e.g., 'include_drill' ignored in single-layer mode, 'layers' with one item yields a single file). This adds immense value beyond the bare 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 'Export Gerber files for manufacturing,' giving a specific verb and resource that clearly distinguishes it from sibling export tools (e.g., export_pcb, export_netlist, export_3d). It further clarifies the output mode (single file vs directory) and key output fields, leaving no ambiguity about the tool's function.

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?

While it doesn't name sibling alternatives explicitly, it provides clear context on when this tool is appropriate (manufacturing output) and explains the two behavioral modes (single-layer vs multi-layer). The description implies usage through its detailed mode logic but could have gone further to say 'use this instead of X when you need Gerber files.' The guidance is clear and practical.

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 that it runs kicad-cli, generates a netlist file, and returns parsed component/net data with sheet paths. This adds behavioral context beyond the annotations (idempotentHint=true, destructiveHint=false) by clarifying the underlying execution and return format. It does not fully detail file overwrite behavior, but the idempotency annotation mitigates that need.

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 efficient and front-loaded: it states the core purpose in the first sentence, then briefly outlines the method and arguments. No fluff or repetition, and every sentence adds value.

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

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

For a two-optional-parameter tool with an output schema, the description covers all essential aspects: what it does, how it runs (kicad-cli), what it returns (parsed data with sheet paths), and parameter meanings. It is complete enough 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?

With 0% schema description coverage, the description fully compensates by explaining both parameters: schematic_path is the root .kicad_sch file, output_dir is the directory for netlist output, and both are optional with defaults. This provides meaningful guidance that the raw schema lacks.

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 action ('Export a netlist from the root schematic') with a distinct scope ('including hierarchy info' and 'sheet path information'). This differentiates it from sibling tool export_netlist, which likely produces a flat netlist, by emphasizing hierarchical detail.

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: use this tool when you need a netlist with sheet path hierarchy for the whole design. However, it does not explicitly mention alternatives or state when not to use it, leaving the agent to infer from the tool's 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?

The description only says 'export' without disclosing potential side effects, such as overwriting existing output files or whether the input PCB file is modified. The destructiveHint annotation indicates the operation may be destructive, but the description does not explain this, and there is no mention of the return value or error handling.

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 concise and well-structured: a one-sentence purpose followed by a clear list of parameters. It avoids unnecessary verbosity and is appropriately sized 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 description does not mention how this tool relates to the many sibling export tools (e.g., export_gerbers, export_3d) or any prerequisites such as having a valid PCB file. It lacks context about when to choose this over others, making it incomplete for a user unfamiliar with the toolset.

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 parameter list includes names and defaults, but only 'units' and 'version' have brief clarifications in the description. 'precision' and 'compress' are left undefined, and the schema provides no descriptions. This lack of explanation for several parameters reduces semantic clarity.

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 exports a PCB to IPC-2581 format for manufacturing data exchange, which is specific and distinguishes it from other export tools. However, it lacks details about the exact content of the output (e.g., layers, options) which prevents a perfect 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 guidance is provided on when to use this tool versus alternative export tools (e.g., export_gerbers, export_pcb). The description does not mention prerequisites or typical use cases, leaving the user uncertain about the optimal context for invoking it.

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

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

Annotations already provide safety context (idempotent, non-destructive, not read-only), and the description adds useful context about output_dir defaults and that spice/spicemodel produce simulator input. However, it does not describe what files are created, whether files are overwritten, or other runtime behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, front-loaded with the core purpose, and uses a clean Args list where every line adds value. It avoids repeating schema details and does not waste 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?

Given the tool's low complexity, the presence of an output schema, and annotations that cover safety, the description covers purpose, parameters, and defaults well. It is only missing explicit tool-selection boundaries relative to export_hierarchical_netlist, but overall it is sufficient.

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 0%, but the description compensates by explaining all three parameters: schematic_path points to a .kicad_sch file, output_dir is an output directory, and format is a netlist format with spice/spicemodel clarified as simulator input. This adds meaning beyond the raw schema defaults and enum values.

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 'Export a schematic netlist' and the title specifies 'for one schematic', clearly identifying the verb, resource, and scope. This distinguishes it from related export tools like export_bom, export_pcb, and especially export_hierarchical_netlist.

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 through the 'one schematic' scope and optional parameters with configured defaults, but it does not explicitly state when to use this tool versus alternatives. It never names export_hierarchical_netlist as the alternative for hierarchical designs.

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 (idempotentHint=true) indicate repeated exports are safe, and the description does not contradict this. It adds useful details such as DXF-specific options (units, contours, etc.) and that layers are required for DXF, which helps the agent understand parameter dependencies. However, it does not disclose things like naming conventions for output files or overwrite behavior, but the annotations cover the safety profile.

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 well-structured with a clear summary line and a parameter list, making it easy to scan. It is slightly long due to the parameter listing, but each line adds value. It is front-loaded with the main purpose, and the parameter documentation is organized.

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 an output schema and no required parameters, the description covers the essential context, especially the DXF-specific requirements. It provides enough information for an agent to use the tool correctly, though it could mention output directory handling and default file naming. The presence of an output schema reduces the need for return value documentation.

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 0%, so the description must compensate for all 9 parameters. The description provides brief explanations for most parameters, but many are minimal (e.g., 'Optional; omit to use the configured default') and do not explain format constraints or default values beyond what the schema shows. It adds clarity on DXF-only options, but lacks deeper semantics like allowed layer names or how output paths are constructed.

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 exports a PCB to PDF, SVG, or DXF format, distinguishing it from other export tools like export_schematic or export_gerbers. It identifies the key resource (PCB) and the supported output formats, though it does not explicitly differentiate from all sibling export 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 clear usage context: specifies that layers are required for DXF, and that output units and certain options are DXF-only. It implies when to use this tool (for PCB exports in these formats) but does not explicitly state when not to use it or mention alternatives like export_gerbers.

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

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

Annotations already cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds the context that it exports a pick-and-place file, which is useful, but it doesn't disclose details like overwrite behavior, output file naming, or side effects beyond creating the file. This is acceptable but not rich.

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: one purpose line plus a two-item Args block. Every sentence earns its place, and the structure is front-loaded with the main purpose, making it easy for an agent to quickly understand.

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 (two optional parameters), existing annotations, and an output schema, the description is mostly complete. It covers the main purpose and parameter semantics. Minor gaps include lack of emphasis on whether the output directory must exist, but this does not significantly hinder selection or 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 0%, so the description carries the full burden. It clearly explains both parameters: pcb_path (path to .kicad_pcb file, optional with default) and output_dir (output directory, optional with default). This adds meaningful value beyond the bare schema, though it doesn't specify the exact default values.

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 ('Export') and resource ('component position file') with a clarifying parenthetical ('pick and place'), which distinguishes it from other export tools like export_schematic or export_bom. This makes the purpose immediately clear and 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 implies usage by clearly stating what the tool does, but it does not explicitly compare against alternatives or provide when-to-use/when-not-to-use guidance. In a list with many other export tools, there's no explicit differentiation beyond the purpose statement.

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 explains format-specific output behavior: single vs multiple files, path semantics, and filled fields (size_bytes, files, count). It also clarifies optional parameters and defaults. This adds context 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 well-structured with a clear opening sentence, followed by format-specific behavioral notes, and an Args section. It is somewhat verbose but all content is relevant to invoking the tool correctly.

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 behaviors and parameter semantics, and the presence of an output schema likely documents return values. It misses potential error scenarios and prerequisites, but for an export tool this is adequate.

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 parameters have no descriptions (0% coverage), so this description carries the full burden. It explains the meaning of each parameter: format enum values, optional schematic_path and output_dir with defaults. It also explains the impact of format on output structure.

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 'Export schematic to PDF, SVG, or DXF format' with a specific verb, resource, and output formats. This clearly distinguishes it from sibling export tools like export_netlist, export_pcb, and export_gerbers.

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 context for use, mentioning that pdf/dxf produce a single file while svg produces one per sheet, which helps the agent set expectations. However, it does not explicitly compare with alternative tools or state when not to use it.

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