mcp-server-kicad
Server Quality Checklist
Latest release: v0.20.1
- Disambiguation3/5
With 109 tools, there are several overlapping or closely related names (e.g., get_symbol_info vs get_symbol_pins, add_symbol vs add_lib_symbol, remove_label vs remove_hierarchical_label). While descriptions mostly clarify the differences, the sheer volume makes misselection likely, and convenience wrappers like auto_place_decoupling_cap and wire_pins_to_net add to potential confusion.
Naming Consistency4/5The vast majority of tools follow a clear verb_noun snake_case pattern (list_*, add_*, remove_*, export_*). Minor exceptions like is_root_schematic (a predicate rather than an action) and no_connect_pin (a command phrase) break the strict action-first pattern, but overall naming is highly consistent.
Tool Count1/5At 109 tools, this is far beyond the recommended range and clearly falls into the '50+ tools' extreme mismatch category. The server attempts to cover the entire KiCad EDA workflow, but this bloat makes model selection and tool enumeration costly, and many tools could be consolidated into parameterized families.
Completeness3/5The server covers most core workflows: schematic creation/editing, PCB design, exports, ERC/DRC, and hierarchy. However, there are notable gaps such as no tool to add bus entries, no modify_text, and no in-place label editing, which are significant for a design tool of this scope.
Average 4.1/5 across 107 of 109 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- 3 of 3 community issues answered or closed in the last 6 months
- 231 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
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.
Conciseness4/5Is 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.
Completeness2/5Given 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.
Parameters2/5Does 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.
Purpose4/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior1/5
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.
Conciseness4/5Is 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.
Completeness2/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no hints (all false), so the description must disclose behavior. It only says 'Add' and describes arguments, but doesn't mention side effects such as modifying the schematic file, whether it requires an existing open project, or what happens on invalid input. This is a significant transparency gap 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action. The Args list is compact and directly pairs each parameter with its type and purpose. No unnecessary words or redundancy; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, return-value details are not needed. However, the description lacks context about the modification workflow (e.g., whether this is a file-writing operation, how it interacts with existing wires). For a simple mutation tool it's borderline adequate, but an agent would still have open questions about side effects and prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the parameter-documentation burden. It adds meaningful context: 'points' is a list of junction positions with x/y keys, and 'schematic_path' is an optional path to a .kicad_sch file with a configured default. This goes beyond the schema titles and provides usable guidance, though it could detail coordinate units.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Add multiple junctions', which is a clear verb+resource combination. It distinguishes itself from related tools like remove_junction by being explicitly additive and plural, though it doesn't reference alternatives or scope in a way that fully differentiates it from other schematic-modification tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., an existing schematic) or situations where adding junctions is appropriate. The description simply states what it does without any 'use this when' or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters4/5Does 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.
Purpose4/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description must explain side effects, coordinate units, or file modification behavior, but it doesn't. It only states the parameter format, offering no insight into what happens when wires are added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and front-loaded with the essential action. Every sentence provides value, with no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set and presence of an output schema, the description covers the essentials. However, it omits details like coordinate system, file existence prerequisites, or whether the operation is atomic, leaving some gap in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates by explaining the 'wires' parameter as a list of wire defs with keys and the 'schematic_path' as an optional path to a .kicad_sch file with default fallback. This adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add multiple wires at once') and specifies the resource (wires) with coordinate keys. It distinguishes from other schematic tools by focusing on batch wire addition, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., removing wires, adding labels). The description implies usage via the name, but lacks context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness2/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior3/5
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.
Conciseness4/5Is 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.
Completeness3/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds the behavioral note that footprint_path is optional and falls back to a configured default. However, it does not elaborate on error handling or other runtime behaviors, so it neither fully leverages nor contradicts 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose, followed by a structured Args section. Every sentence serves a role. The misleading 'Optional' label, though, detracts from overall quality and prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema and annotations covers return values and safety, reducing the burden on the description. Still, the description misses usage context and contains a param requiredness contradiction, making it only minimally complete for a one-parameter read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning by identifying footprint_path as a path to a .kicad_mod file and mentioning an optional default. However, it directly contradicts the input schema, which marks footprint_path as required. This inconsistency is a significant flaw, especially since schema coverage is 0% and the description was expected to fully compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 ('Get') and resource ('pad and outline details for a footprint .kicad_mod file'). This distinguishes it from sibling tools like get_footprint_pads or get_footprint_bounds, which focus on specific subsets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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 only states what it does and describes the argument, leaving the agent to infer usage from context. No explicit exclusions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive, covering the safety profile. The description adds the context that it reads from lib_symbols and that schematic_path has a default, but it doesn't disclose behavior for missing symbols or the exact structure of returned pin info. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences and a focused Args list. Every sentence adds value, information is front-loaded, no emptiness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering the risk profile, the description adequately covers the simple two-parameter operation. It lacks guidance on interacting with sibling tools, but the core invocation is documented well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates by explaining both parameters with an example for symbol_name and optional/default behavior for schematic_path. It gives useful semantics beyond the raw schema but doesn't specify the exact string format for symbol_name or path resolution.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly uses verb 'Get' and specifies resource 'pin info for a symbol in the schematic's lib_symbols', distinguishing it from other schematic queries. However, it doesn't explicitly differentiate from sibling tool get_pin_positions or clarify what 'pin info' includes (names/numbers vs. positions). Slight vagueness prevents a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs alternatives like get_pin_positions or get_symbol_info. The description only states the operation and doesn't mention exclusions or prerequisites. The optional schematic_path hint implies a context but doesn't provide explicit use-case guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the read-only behavior is established. The description adds useful context by specifying that it lists only 'named' nets and that pcb_path can be omitted to use a configured default. It does not disclose return format or error handling, which is acceptable for a simple read-only tool with an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the primary action, and contains no filler. The parameter explanation is compact and directly informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, annotations, and the presence of an output schema, the description sufficiently covers the purpose and the optional parameter. It could add minor details about default path resolution or error cases, but these are not critical for a straightforward list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a default of '' with no description, while the description explains pcb_path is a path to a .kicad_pcb file and that omitting it uses a configured default. This meaningfully goes beyond the schema and fully compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List all named nets on the PCB.' The verb 'List' and resource 'named nets' are specific, and the phrase 'named nets' adds scope that distinguishes it from other net-related tools like get_net_connections or list_pcb_traces. However, it does not explicitly name alternative tools, so it stops short of a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description only explains the purpose and the optional parameter, but does not mention any conditions, exclusions, or alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is clear. The description adds a minor behavioral detail with 'all placed components', implying unplaced or library components are not included, but it does not elaborate on filtering, ordering, or output structure beyond what the output schema likely covers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one opening sentence plus a single parameter definition. It is front-loaded with the core purpose and includes only essential information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with one optional parameter and an output schema, the description provides sufficient context: the operation type, scope ('all placed components'), and parameter semantics. It does not mention edge cases like empty schematics or invalid paths, but these are not critical given the tool's simplicity and existing annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 explains schematic_path as 'Path to .kicad_sch file. Optional; omit to use the configured default.' This adds file-format context, optionality, and fallback behavior beyond the schema field alone, fully compensating for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all placed components in the schematic' with a specific verb and resource. It differentiates from sibling list tools (e.g., list_schematic_labels, list_schematic_wires) by focusing on 'components', though it doesn't explicitly contrast with those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives is provided. The only usage context is the parameter description ('Optional; omit to use the configured default'), which explains the path argument but does not help select among the many list_schematic_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Idempotent: calling again for a pin that already has one is a no-op', but the annotations set idempotentHint to false. This is a direct contradiction. Additionally, no other behavioral traits such as file modification or error cases are disclosed beyond the basic annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact with a clear one-line purpose, an idempotency note, and a structured Args list. No redundant or filler content. It is well-front-loaded and each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with an output schema, the description covers the operation, all parameters, and idempotency. However, it lacks usage guidance and contradicts its idempotency annotation, which slightly reduces completeness. Overall, it is mostly complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions for any parameter (0% coverage), so the description fully compensates. It provides examples for reference ('U2'), pin_name formats ('NC' or '3'), and clarifies schematic_path as optional with a default. Every parameter is meaningfully explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Place a no-connect flag on a component pin', using a specific verb and resource. It differentiates from siblings like remove_no_connect by indicating the action of placing. The arg examples further clarify the intended use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives such as remove_no_connect or connect_pins. It only describes the operation and idempotency, with no explicit context or exclusions. Given the many sibling tools, this lack of distinction is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose any behavioral aspects beyond the annotations. It doesn't explain side effects, output, or requirements. Annotations indicate it is not read-only and is idempotent, but the description adds no extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a clear front-loaded purpose sentence and a compact arg listing. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and an output schema exists, so return values need not be explained. However, the description does not explain what a jobset is or when to run it, leaving some contextual gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the one parameter ('jobset_path') as a path to a .kicad_jobset file, adding meaning beyond the schema's plain string type. This compensates for the low schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Run') and specific resource ('a KiCad jobset file'), making the tool's purpose unambiguous. It is distinct from sibling tools, which mostly target schematics, PCB, or export operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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, nor does it mention exclusions or prerequisites. It simply states the action and arguments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters2/5Does 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.
Purpose5/5Does 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.
Usage Guidelines2/5Does 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so no safety signals are provided. The description adds the detail that pcb_path is optional and falls back to a configured default, which is useful, but it does not disclose whether the operation modifies the file in place, requires an existing board, or performs any DRC checks. Side effects and prerequisites remain unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a one-sentence purpose followed by a clearly formatted Args list. Every parameter is explained without extraneous text. The structure is scannable and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all 8 parameters and the core purpose, but it lacks some context: coordinate units are not specified, and there is no mention of what happens if the pcb_path is invalid or whether the operation is undoable. Given the tool's complexity, the description is reasonably complete but leaves a few important gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only names and defaults with no descriptions, so the description carries full responsibility. It explains each parameter: coordinates as start/end points, width in mm, layer with examples, net as number, and pcb_path with optionality guidance. This adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Add a trace segment between two points,' which clearly identifies the verb (add), resource (trace segment), and scope (between two points). This distinguishes it from sibling tools like add_via or add_pcb_line. The parameter list reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives such as add_pcb_line or add_via. There is no mention of scenarios where add_trace is appropriate or inappropriate, and no reference to sibling tools. The only hint is the parameter list, which implies PCB routing, but no explicit 'use when' guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false (not read-only, not open-world, not idempotent, not destructive), so the description bears the burden of explaining mutating behavior. It never states that placing a component will add it to the schematic, whether duplicate references are allowed, or if it modifies existing schematic files. It only mentions path resolution, leaving critical side effects undisclosed. This is insufficient for a write operation with no idempotency guarantee.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose sentence followed by a compact, bulleted Args list. It is moderately lengthy due to 10 parameters, but every line adds value—no filler. The front-loaded purpose aids quick understanding. Slight verbosity in repeating all optional path details could be trimmed, but overall it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 params, mutation, no output schema shown), the description covers parameter semantics and some usage context, but lacks critical behavioral details (e.g., overwrite behavior, error handling) and does not position itself against sibling placement/addition tools. The optional path defaults and hierarchy resolution are useful, yet the overall description leaves gaps in what happens on invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only titles (e.g., 'X', 'Y', 'Value') with no descriptions (schema_description_coverage=0%). The description's Args section fully compensates: it explains each parameter with type examples (lib_id: 'Device:R', reference: 'R1'), units ('schematic units (mm)'), allowed values (rotation: 0,90,180,270), and optionality (paths: 'Optional; omit to use the configured default'). This adds essential meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Place a schematic symbol') and enumerates component types (resistor, capacitor, etc.) and specific libraries ('Any lib_id in a library works'). It distinguishes this from sibling tools like move_component (which moves) and remove_component (which deletes) by focusing on placement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides practical guidance on optional parameters (e.g., 'symbol_lib_path' for custom libraries, 'project_path' for hierarchy resolution) and tells users to omit optional args to use defaults. However, it does not explicitly state when to use this tool versus alternatives like 'add_symbol' or 'place_footprint', nor any exclusions. The usage context is implied but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no helpful context (all hints are false), so the description carries the full burden. It only states the literal action 'Add a via' without disclosing side effects (e.g., modifies the PCB file), required state (e.g., board must be loaded), or consequences of misconfiguration. This is a mutation operation with no behavioral transparency beyond the basic verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-line summary followed by a clean 'Args:' list. Each parameter gets a concise explanation. There is no redundant fluff, and the format is easy to scan and parse. The information is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity tool with 7 parameters and an output schema available, the description covers the parameters and core behavior adequately. It lacks preconditions (e.g., the pcb_path must point to an existing .kicad_pcb file) and any note about the operation's effect on the board, but the parameter list is complete and the output schema likely covers return values. This is above average but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates well by explaining each parameter's meaning, including units for size and drill (mm), the default layers, and the optionality of pcb_path. However, some parameter semantics are thin (e.g., 'net' is only described as 'Net number' without clarifying what the number refers to), leaving room for improvement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a via at a position' with a specific verb and resource. It distinguishes itself from sibling tools like add_trace or add_copper_zone by explicitly targeting vias. The action is unambiguous and directly tied to the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating the action ('Add a via at a position'), but it does not provide explicit guidance on when to use this tool versus alternatives or mention any prerequisites or context. There is no 'when to use' or 'when not to use' statement, which is a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds minimal behavioral context beyond the summary nature (page info and item counts), but does not disclose return format, pagination, or edge cases. Given the annotations, this is adequate but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence for the tool purpose and a short Args section for the parameter. Every sentence adds value, and the key information is front-loaded. There is no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, read-only annotations, and an output schema indicated in context), the description covers all necessary aspects: what it does and how to invoke it. It is complete enough for an agent to select and call this tool correctly without additional clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines schematic_path as a string with a default, and the schema description coverage is 0% because the description adds the semantic meaning: 'Path to .kicad_sch file. Optional; omit to use the configured default.' This explains the parameter's purpose and optionality, going beyond the schema's bare type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') with a clear resource ('schematic page info and item counts'), which conveys what the tool does. However, it does not explicitly differentiate from sibling tools like get_sheet_info or list_schematic_components, though the focus on 'summary' and 'item counts' provides some distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes the schematic_path is optional and explains the default behavior ('omit to use the configured default'), which is useful. It does not, however, state when to use this tool relative to alternatives such as list_schematic_components or get_sheet_info, leaving usage context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true and readOnlyHint=false, but the description safely adds that it returns a structural report with violation lists and coordinates, and mentions it writes a report file to output_dir. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded, with a clear purpose statement and parameter explanation. No redundant content, though the return value mention is somewhat vague.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists rings, the description sufficiently covers the output nature, but it omits any prerequisites (e.g., PCB must exist, valid path) and does not specify what happens when violations are found vs. none. It could also mention the default output directory resolution more precisely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are explained in the description (path to .kicad_pcb file and directory for report), adding meaning beyond the schema which has only defaults. The description clarifies the file type and default behavior, though it could specify output file naming.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a Design Rules Check (DRC) on a PCB, which is specific and unambiguous. It distinguishes from similar tools like run_erc (electrical rules check) by explicitly naming DRC, and from other PCB-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes both arguments are optional and explains their defaults, but provides no guidance on when to use this tool versus alternatives like run_erc or check_placement. No conditions or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no safety profile (all flags false), so the description carries the full burden. It explains parameter effects (portrait swap, custom size) and the optional schematic_path default, but does not disclose that the tool modifies the schematic file, what happens if the file doesn't exist, or whether the change is persistent. This leaves key behavioral aspects undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single purpose sentence followed by a structured Args list. Each line adds necessary information without redundancy, 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.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With five parameters, conditional requirements, and an output schema present, the description covers parameter semantics well. However, it omits broader context such as file modification behavior, error conditions, and relationship to other schematic operations. It is adequate for calling the tool correctly but not fully complete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions (0% coverage), so the description fully compensates. It lists valid size values, specifies units (mm), marks width/height as conditionally required, explains portrait behavior, and clarifies the optional schematic_path. This is far richer than the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states "Set the schematic page/sheet size" with a specific verb and resource, making the tool's purpose unambiguous. It clearly distinguishes from sibling tools like set_trace_width and set_net_class.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed parameter-level usage instructions (e.g., width/height required when size='User', portrait swaps dimensions), but it does not explicitly state when to use this tool versus alternatives or mention prerequisites like file existence. Usage is implied by the name and description, but not explicitly contextualized.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters3/5Does 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.
Purpose4/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the default pcb_path behavior, which is useful 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, with a clear opening sentence and a structured Args section. Every sentence adds value, and it is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with two parameters and an output schema, the description covers invocation details well, including parameter meanings and defaults. It does not describe the return format, but the output schema presumably covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates by explaining each parameter: reference with examples ('R1', 'U1') and pcb_path as an optional file path with default behavior. This exceeds what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets pad info for a placed footprint on the PCB, using a specific verb and resource. It implies distinction from library footprint tools, though it does not explicitly name alternatives like get_footprint_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context (placed footprint, reference-based) and explains the optional pcb_path with default behavior, but it does not mention when to use this tool versus alternatives or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a minor clarification about the default schematic path behavior, but this is also implied by the schema default. No other behavioral details (e.g., return format, performance) are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: a clear one-line purpose followed by a structured Args section. It is front-loaded, avoids redundancy, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and strong annotations, the description is adequate for a read-only list operation. It clearly defines the scope of 'cross-sheet nets' and the optional path. A slight gap is that the distinction between 'hierarchical pins' and 'global labels' may be ambiguous to newcomers, but this is acceptable for the target audience.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does 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 so effectively by explaining the sole parameter's purpose ('Path to root .kicad_sch file'), optionality, and fallback behavior ('omit to use the configured default'). This fully clarifies the parameter beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List all nets that cross sheet boundaries' with the qualifier '(hierarchical pins and global labels)'. This clearly distinguishes it from siblings like list_schematic_global_labels (labels, not nets) and trace_hierarchical_net (single-net tracing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention related tools such as trace_hierarchical_net or get_net_connections, nor does it state any exclusions or preferred contexts. The description only restates the purpose and parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the scoping to 'net labels' and the optionality of schematic_path, but does not disclose additional behavioral traits such as output format or edge cases, so it provides limited extra value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one purpose sentence and a compact Args block. Every word earns its place, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with an output schema and thorough annotations, the description is mostly complete. It covers the action, scope, and parameter semantics. However, it could explicitly mention that this tool is for regular net labels, not global or hierarchical labels, to remove minor ambiguity given the sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates for the single parameter: it explains schematic_path as 'Path to .kicad_sch file' and notes that it is optional with a configured default. This adds clear meaning beyond the raw schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'List all net labels in the schematic' with a specific verb and resource. The phrase 'all net labels' clearly distinguishes this from sibling tools like list_schematic_global_labels and list_schematic_hierarchical_labels, which cover other label types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. Sibling tools for global and hierarchical labels exist, but the description does not mention them or any exclusions, leaving the user to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no read-only or destructive hints (all false), so the description carries the full burden. It discloses that rotation None keeps the current rotation, but it does not mention side effects like whether the schematic file is modified in place, how connectivity is affected, or if the operation is reversible. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a one-sentence purpose followed by a clean args list. Every line adds value—no filler, and the format makes parameters easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully documents all parameters and a clear purpose, and an output schema exists, so return values need no explanation. It lacks explicit behavioral context (e.g., file modification side effects) and differentiation from siblings, but for a simple move operation with a clear argument list, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial meaning to every parameter: reference is a reference designator (e.g., 'R1'), x/y are new positions, rotation is in degrees with explicit None behavior, and schematic_path is optional with a configured default. This is essential given the schema has 0% description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Move a placed component to a new position,' which uses a specific verb ('move') and resource ('placed component') to clearly state the operation. This distinguishes it from sibling tools like place_component (adding new components) and move_footprint (PCB-level moving).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for already-placed schematic components (via 'placed component') and clarifies the optional schematic_path, but it does not explicitly state when to use this tool over alternatives or include exclusions. Sibling tools like place_component and remove_component are not referenced, leaving some ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide minimal guidance (all hints false), so the description carries the burden. It states the action (change width) and filters but does not disclose what happens when no traces match, whether the operation is reversible, or any side effects on the board. It only mentions optional pcb_path. This leaves significant behavioral ambiguity 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact docstring with a clear opening sentence and a structured Args list. Every line provides necessary information without fluff, and the required filter constraint is highlighted. This is well organized and appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core operation, prerequisites, and all parameter meanings, and the output schema likely handles return values. However, it omits edge-case behavior such as when no filters match or multiple traces are affected, and lacks any note about the operation's scope within the PCB context. Given the number of parameters and mutation nature, it is reasonably complete but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions cover 0% of parameters, so the description must fully document them. It does, explaining width units (mm), filter semantics for net_name, layer, and bounding box coordinates, and pcb_path optional behavior. Each parameter receives a concise yet meaningful explanation, making this a strong compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool changes the width of existing traces, using a specific verb and resource. It distinguishes from sibling tools like add_trace, remove_traces, and list_pcb_traces by focusing on width modification, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that at least one filter is required, providing a key usage constraint. It does not explicitly compare to sibling tools or list when to prefer this tool over alternatives, such as using add_trace for new traces or remove_traces for deletion. This is a moderate gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness3/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds no additional behavioral context beyond mentioning optional defaults for parameters. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the purpose, followed by a compact Args list. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool, the description covers purpose and parameters. An output schema exists, so return values need not be explained. It lacks usage guidance but is otherwise complete for a basic export function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description compensates by explaining each parameter (symbol_lib_path as path to .kicad_sym file, output_dir as output directory) and noting they are optional with configured defaults. This adds meaningful semantics beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Export symbol library to SVG images.' which is a specific verb+resource and distinguishes it from sibling export tools like export_footprint_svg.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the purpose, but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or context for when it should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the semantic of checking root vs. sub-sheet status, but does not disclose additional behavioral details such as return format or error handling. No contradiction with annotations; consistent with read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence plus a parameter doc line. No unnecessary words or repetition of structured fields. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, a single parameter, strong annotations, and the presence of an output schema, the description is complete enough for an agent to understand and invoke it. It could include usage guidance, but that is addressed in the usage dimension, so overall completeness is satisfactory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no description for schematic_path (0% coverage). The description compensates fully by specifying 'Path to .kicad_sch file' and explaining the default behavior: 'Optional; omit to use the configured default.' This gives clear meaning to the only parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Check if a schematic is the root or a sub-sheet.' It uses a specific verb ('Check') and resource ('schematic'), and the focus on hierarchy status distinguishes it from sibling list tools like list_schematic_sheets or get_sheet_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like list_hierarchy or validate_hierarchy. It explains what the tool does and its parameter, but does not mention appropriate contexts, exclusions, or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey the safe, read-only, idempotent nature. The description adds minimal behavioral context by specifying the target file type and that the parameter is optional with a configured default, but it does not disclose error handling or edge cases. Given the strong annotations, the description contributes some additional value but is not rich in behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence followed by a concise parameter definition, with the main action front-loaded. There is no redundancy or extraneous information, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional parameter, strong annotations, and an output schema, the description covers essential usage. However, it could enhance completeness by briefly noting when to choose this tool over related ones like list_lib_footprints, though this is not critical given the clear purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining symbol_lib_path as a path to a .kicad_sym file and its optionality with a default behavior. This goes beyond the bare schema property, which only has a title and default, providing meaningful guidance for the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and resource 'all symbols in a .kicad_sym library file', which clearly states the operation and distinguishes it from sibling tools like list_lib_footprints. The scope is unambiguous and immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing symbols in a .kicad_sym file and notes the optional path with a configured default, but it does not explicitly state when to use this tool versus alternatives. There is no mention of alternatives like list_lib_footprints, so the guidance is inferred rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds the scope of operation (all graphic items) and the optional pcb_path behavior, but does not disclose return format or error handling. This is adequate given the simple read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first states the purpose, and the second documents the sole parameter. Every word contributes value, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with an output schema and comprehensive annotations, the description covers both purpose and parameter semantics. No additional information about return values is needed since an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage for pcb_path, so the description carries the full burden. It clearly explains that the parameter is a path to a .kicad_pcb file, is optional, and omitting it uses the configured default. This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'list' and identifies the resource as 'graphic items (lines, text, etc.) on the PCB'. This clearly distinguishes it from sibling tools like list_pcb_traces and list_pcb_footprints by focusing on a distinct category of PCB elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description simply states what it does without mentioning any exclusions or specific use cases, leaving the agent to infer applicability 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false (no hints), so the description carries the burden. It discloses a significant behavioral detail: specifying the 'other side' in the layer parameter triggers a full flip with mirroring of pads, graphics, and text justification, matching KiCad's flip, and that it refuses to flip footprints with unmeasured constructs rather than half-transforming. This is valuable transparency beyond the basic action. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a lead sentence and an Args list. The layer parameter's explanation is detailed but necessary for understanding a critical side effect, and every sentence contributes. It is slightly long but not verbose, earning a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, flip behavior, optional path) and lack of annotations, the description covers key edge cases (flip and refusal) and parameter semantics. It does not explain potential effects on existing placement (e.g., does it move the footprint regardless of overlapping?) or whether the PCB file is modified, but the presence of an output schema likely covers return values. Overall, it is fairly complete for its domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only source of parameter meaning. It explains all six parameters: reference (with example), x and y (new positions), rotation (None = keep current), layer (includes the detailed flip behavior), and pcb_path (optional with default). This adds substantial meaning beyond the schema's bare titles and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear, specific action: 'Move a footprint to a new position,' which unambiguously identifies the tool's purpose (verb 'move' + resource 'footprint'). It distinguishes from sibling tools like place_footprint, remove_footprint, and move_component by specifying the PCB footprint context, making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any explicit guidance on when to use this tool versus alternatives. It only states the action and parameter details. There is no mention of situations where this tool is preferred over place_footprint (for initial placement) or move_component (for schematic components). Usage is implied by the tool name and action but not explicitly stated, making it a gap for agents deciding among similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the modification nature is known. The description adds 'including all pins' which clarifies the scope of the move, but it does not disclose side effects like connectivity changes or undo behavior. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main action sentence, followed by a structured Args list. It is concise, though the Args section could be tightened; overall it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers the move operation, all pins, and all parameters. An output schema exists, so return values need not be described. It lacks mention of potential side effects, but the core invocation context is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides zero descriptions (0% coverage), but the 'Args' section fully explains each parameter: UUID purpose, X/Y in mm, and schematic_path optional semantics with default behavior. This greatly exceeds the schema by adding units, context, and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Move') and resource ('a hierarchical sheet block') with a notable scope ('including all pins'). This distinguishes it from siblings like move_component or move_footprint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by naming the operation but does not explicitly state when to choose this over alternatives, nor does it mention any exclusions or prerequisites. Sibling tools like add_hierarchical_sheet and remove_hierarchical_sheet exist, but no comparison is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the destructive nature is covered. The description adds useful context about default schematic_path and UUID disambiguation, but does not disclose what happens on lookup failure or whether the file is modified, though output schema may cover return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient: a single-sentence purpose followed by a minimal bulleted list for parameters. Every line adds value, no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive single-object removal tool with annotations and an output schema, the description is largely complete. It covers target identification and optional path handling. Minor gaps like error behavior when not found are acceptable given existing structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent (0% coverage), so the description carries the full burden. It provides clear definitions for text, schematic_path (including default behavior), and uuid (including disambiguation purpose), adding meaningful guidance beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Remove') and resource ('hierarchical label'), and differentiates from siblings like remove_label by specifying 'hierarchical'. It also clarifies matching by name or UUID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for hierarchical labels and explains how to specify the target, but does not explicitly distinguish from alternatives like remove_label or mention when not to use it. The context of sibling tools and the name make the primary use case clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the destructiveHint annotation by explaining atomicity, the backup file behavior, that exactly one backup exists, and that every run overwrites it. This gives the agent a clear picture of the upgrade's side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose and uses a structured Args section. Though somewhat narrative, the extra details about atomicity and backup behavior are valuable and earned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key operational concerns: destructive behavior, atomic replacement, backup semantics, and the parameter's default. Since an output schema exists, it need not describe return values, and the missing guidance around when to use this tool is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning by identifying symbol_lib_path as a .kicad_sym file and mentioning a configured default. However, it states the parameter is optional while the input schema marks it required, creating a direct contradiction that could mislead an agent into omitting it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the tool's action and target: 'Upgrade a symbol library to current KiCad format.' This is specific and distinguishes it from the sibling upgrade_footprint_lib, which targets a different resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose statement implies when the tool should be used, but there is no explicit guidance about when to use it versus alternatives, nor any exclusions. The description focuses on behavior rather than usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose4/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the root-schematic starting point and the optionality of the path, but does not disclose other behavioral traits like traversal depth or response structure. This is acceptable given the annotations and the presence of an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first defines the purpose, the second documents the single parameter. It is concise, front-loaded, and every sentence provides necessary value. The use of an 'Args' block is a clean way to structure parameter documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and an output schema, the description is largely complete. It could explicitly mention that the hierarchy includes nested sheets recursively, but the phrase 'full sheet hierarchy' implies this. The output schema presumably describes the return structure, so no further detail is required. Annotations handle safety and idempotency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a title and default for schematic_path with no description (0% coverage). The description compensates fully by explaining it is a path to a root .kicad_sch file, that it is optional, and that omitting it uses the configured default. This gives the agent complete information needed to use the parameter correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('full sheet hierarchy') with a clear scope ('starting from a root schematic'). This distinguishes it from sibling tools like list_schematic_sheets, which likely lists immediate sheets only, and get_sheet_info, which likely fetches a single sheet's details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the phrase 'full sheet hierarchy', but it does not explicitly state when to use this tool over alternatives such as list_schematic_sheets or validate_hierarchy. No exclusions or alternative tool names are mentioned. The parameter guidance about using the configured default is helpful but does not address tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating safe read-only behavior. The description adds that it lists .kicad_mod files, which is consistent but does not disclose additional behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two lines: a clear summary and an Args section. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with an output schema, the description is complete. It explains the tool's purpose and its single parameter adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning for the single parameter 'pretty_dir' by specifying it is a path to a .pretty directory containing .kicad_mod files. Schema coverage is 0%, so the description compensates well, though it could be more precise about path format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'footprints', and the context 'in a .pretty library directory'. It distinguishes from siblings like list_pcb_footprints by specifying the library scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for library footprints versus PCB footprints (list_pcb_footprints) but does not explicitly state when to use this tool over alternatives or provide any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that schematic_path is optional and falls back to a configured default, which is useful context. However, it does not discuss error conditions or return format, though an output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the primary purpose, the second explains the only parameter. It is front-loaded, and every phrase adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool, the description is sufficient: it explains what it does and the parameter. The output schema handles return values, and annotations cover safety. It could be improved by describing what constitutes a 'bus entry', but that is domain knowledge likely known to KiCad users. Overall, complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only a title and default for schematic_path, with no description (0% coverage). The description compensates fully by specifying it's a path to a .kicad_sch file, optional, and defaults to a configured path. This gives complete semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'bus entries in the schematic', clearly distinguishing it from sibling list tools like list_schematic_wires or list_schematic_labels. It concisely states the operation without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use for retrieving bus entries but does not provide explicit guidance on when to choose this tool over alternatives or any prerequisites. The optional schematic_path hint is parameter guidance, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that it lists 'all' no-connect flags and notes the optional path behavior, but discloses no further behavioral traits or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise two-sentence structure: the first sentence states the purpose, the second documents the argument. Every sentence earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read-only list operation with an output schema present, so return values are likely documented elsewhere. The description covers the purpose and parameter adequately for this level of complexity, and the annotations cover safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema property for schematic_path has no description (coverage 0%), so the description compensates by explaining it is a path to a .kicad_sch file, is optional, and omitting it uses a configured default. This adds meaningful information beyond the schema's bare title and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'List all no-connect flags in the schematic.' It uses a specific verb and resource, and the phrase 'no-connect flags' distinguishes it from sibling tools like list_unconnected_pins or list_schematic_wires.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives. The purpose implies usage (e.g., to inspect existing no-connect flags), but there is no mention of related tools such as no_connect_pin or remove_no_connect, and no exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds the scope ('all hierarchical sheets') and the optional default path behavior, which is useful context, but does not disclose return format or potential errors. Since annotations handle the safety profile, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the purpose, the second covers the parameter. All information is front-loaded and every sentence earns its place. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with an output schema, the description covers the essential aspects: what it does and what the parameter means. It lacks explicit usage guidance or prerequisites, but given the straightforward nature and good annotations, it is nearly complete. A minor gap is not clarifying whether 'all hierarchical sheets' includes nested sheets recursively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly explains the single parameter: 'Path to .kicad_sch file. Optional; omit to use the configured default.' This provides meaning beyond the input schema, which only has a default empty string and no description. It clearly conveys the parameter's purpose, optionality, and default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all hierarchical sheets in the schematic, using the specific verb 'List' and a specific resource. This distinguishes it from other list_* tools that target different entity types (components, labels, wires, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating what it does, but does not explicitly provide when-to-use context or alternatives. Sibling tools like list_hierarchy and get_sheet_info exist, but no guidance is given on when to prefer this tool over them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructiveHint=true, and the description merely restates 'modify' without adding behavioral context such as side effects, irreversibility, permissions, or file system impact. It does not disclose anything beyond what the annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-sentence summary followed by a concise, line-per-argument list. Every line holds necessary information, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 6-parameter complexity, the presence of an output schema, and annotations, the description sufficiently covers parameter semantics and selection context. It lacks only minor behavioral details like saving or file write effects, which are not required due to annotations and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description's Args section fully compensates by explaining each parameter's meaning and default behavior (e.g., 'None = keep', 'empty = keep', and source of sheet_uuid). This is critical for correct invocation and adds significant value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool modifies properties of an existing hierarchical sheet block, using a specific verb and resource. This distinguishes it from sibling tools like add_hierarchical_sheet, remove_hierarchical_sheet, and move_hierarchical_sheet.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating it operates on an existing sheet identified by sheet_uuid from list_schematic_sheets. It implies when to use it (modify existing) but does not explicitly name alternatives like add or remove, so it lacks explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint: true, which aligns with the description's 'Remove' action. The description adds limited context by specifying that schematic_path is optional and falls back to a configured default, but it does not disclose details such as irreversibility or behavior if the junction is not found. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core action, and uses a clean bullet-style list for parameters. Every sentence contributes useful information; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, three-parameter destructive tool with annotations and an output schema, the description is largely complete. It clearly states what the tool does and how to invoke it, though it could mention the file-modifying effect explicitly. However, the destructiveHint annotation covers this, and the output schema covers return values, so the description suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the full burden of explaining parameters. It explicitly defines x as X position, y as Y position, and thoroughly explains schematic_path as a path to the .kicad_sch file, noting it is optional with a default. This adds significant semantic value beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Remove a junction') on a specific resource ('at the given coordinates'), clearly distinguishing it from sibling removal tools like remove_wire or remove_label. The verb-noun pairing is unambiguous and contextually appropriate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit usage context by requiring coordinates and an optional schematic path, but does not explicitly state when to use this tool over alternatives or mention any exclusions. It is clear that this tool is for junctions specifically, yet direct guidance on when not to use it is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds the context that schematic_path is optional and falls back to a configured default. However, it does not disclose side effects or failure behavior, so beyond annotations it offers only minimal extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: one purpose sentence followed by a concise Args list. Every sentence adds value, and the structure is front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and the output schema exists, so return values are likely covered. The description explains all parameters and the default path behavior. Missing are potential failure conditions or idempotency notes, but these are not critical given the simplicity and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description's Args section clearly explains each parameter: sheet_uuid is the sheet's UUID, pin_name is the pin to remove, and schematic_path is the optional path to the parent .kicad_sch file with a default when omitted. This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Remove a pin from a hierarchical sheet block' – a clear verb+object. It distinguishes from sibling removal tools like remove_hierarchical_label or remove_component by specifying 'sheet pin'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It only mentions the optional schematic_path parameter and its default behavior. No exclusions or alternative tool references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not add behavioral context beyond what annotations already provide. Annotations mark destructiveHint=true, and the description merely repeats the mutating nature with 'Reorder'. There is no disclosure about file modification, irreversibility, or side effects, so the value added is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a one-sentence purpose statement and a short args list. No filler words or redundant information. Information is front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 clear annotations, the description covers purpose and parameters adequately. It could be more complete by noting prerequisites (e.g., UUIDs must refer to existing sheets) or error behavior, but these are not critical given the schema and context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does 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 'page_order' as a list of sheet UUIDs and 'schematic_path' as an optional path to the root .kicad_sch file, including the default behavior. This provides essential meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reorder'), the target resource ('hierarchical sheets'), and the method ('by specifying the desired UUID order'). It distinguishes itself from sibling tools like move_hierarchical_sheet or duplicate_sheet by focusing on global page ordering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose inherently conveys when to use it: when the user wants to change the order of schematic pages. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to select this tool over siblings that move individual sheets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it traverses hierarchical pins/labels and supports an optional path, but it does not disclose behaviors for missing nets, partial matches, or output shape beyond schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence for purpose and a short Args list. It front-loads the key action and resource, with no redundant phrasing or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, an output schema exists, and annotations cover safety, the description adequately covers purpose and parameters. It could add more context on expected use cases or limitations, but the essentials are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage (no property descriptions), but the description's Args section fully explains both parameters: net_name as the net/label name to trace, and schematic_path as the root .kicad_sch file path with a default fallback. This completely compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'trace' with resource 'net across the hierarchy' and explicitly mentions 'following hierarchical pins and labels', which clearly distinguishes it from sibling list functions like list_cross_sheet_nets or validate_hierarchy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for tracing a net's path through hierarchy but does not provide explicit when-to-use guidance or contrasts with alternatives (e.g., list_hierarchy, list_cross_sheet_nets). It's clear enough for basic use but lacks exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, which cover safety. The description adds specific behavioral context by stating what validation is performed (against keep-out zones and board edge), which is not already in the annotations. It doesn't contradict the annotations and provides useful domain-specific behavior beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear one-sentence purpose followed by a simple Args section. No unnecessary words, and the content is front-loaded with the main action. It earns every sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter, read-only annotations, and an existing output schema, the description covers essential usage. The main purpose is clear, and the parameter is fully documented. A minor gap is the lack of distinction from the sibling check_placement, which could cause confusion, but overall the description is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter, pcb_path, with a type and default but no description (0% coverage). The description fully compensates by explaining it as 'Path to .kicad_pcb file. Optional; omit to use the configured default.' This provides complete parameter meaning that the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Validate all footprint placements against keep-out zones and board edge.' This is a specific verb ('validate') with a specific resource ('footprint placements') and scope ('keep-out zones and board edge'). It effectively distinguishes itself from broader tools like run_drc by focusing on placement validation, although it doesn't explicitly differentiate from the sibling check_placement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It doesn't mention 'use instead of check_placement or run_drc' or indicate prerequisites like 'before running DRC.' The purpose implies usage for placement validation, but no contextual or alternative-based guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the default library path behavior and the fact that it returns detailed pin/property info, but it does not disclose additional behavioral traits such as error handling, performance characteristics, or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose, followed by a structured Args section. Every sentence adds value, and the example helps grounding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given 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 rich annotations, the description covers the essential invoke-time information. It does not describe return fields, but the output schema handles that. The only minor gap is not explicitly distinguishing this from the similar get_symbol_pins tool, but the wording is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 each argument with examples and clarifying that symbol_lib_path is optional and defaults to the configured library. This adds meaning beyond the bare schema property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with a clear resource: 'detailed pin and property info for a symbol in a library.' This distinguishes it from siblings like get_symbol_pins and list_lib_symbols by emphasizing both pin data and property data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by listing required and optional arguments, including an example symbol name and the behavior of omitting symbol_lib_path (uses default). It gives no explicit exclusions or references to alternatives, but the purpose statement implies when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to justify safety. It does add context about the optional path and configured default, but doesn't disclose return format or behavior across nested sheets. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences and an Args section. Every word earns its place, front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, read-only, output schema exists), the description is adequately complete. It could mention whether wires from sub-sheets are included, but for a straightforward list operation, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description's Args section fully explains schematic_path: its purpose, file type (.kicad_sch), optionality, and default behavior. This compensates well for the lack of schema descriptions, though it could specify what the 'configured default' is.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all wire segments in the schematic' with a specific verb and resource. It distinguishes this tool from sibling list tools (e.g., list_schematic_components) by explicitly targeting wires.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (to list wires) and even explains the optional schematic_path parameter and default behavior. It lacks explicit alternative comparisons or exclusions, but the context is straightforward and unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior3/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral traits beyond annotations: it uses place_component internally, places a PWR_FLAG automatically, and notes that power symbols are regular symbols with isPower=True. It also explains optional path parameters. No contradiction with annotations (all false).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and efficiently structured: a one-sentence purpose, a brief note on internal behavior, and a clean Args list. Every sentence adds value without redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with an output schema present, the description covers the action, internal mechanism, auto-flag side effect, and parameter semantics thoroughly. It misses only minor details like return values or error scenarios, but those are covered by the output schema and annotations imply mutation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates with an Args section that explains every parameter, including examples for lib_id and reference, units for x/y, rotation degrees, and optional path behaviors. This adds substantial meaning beyond the bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource statement: 'Place a power symbol (VCC, GND, +3V3, etc.)'. It distinguishes from sibling tools like place_component by noting it uses place_component internally and adds a PWR_FLAG, making the specific purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied rather than explicitly stated. It explains that power symbols come from the 'power' library with isPower=True and that a PWR_FLAG is auto-placed for ERC, which tells the agent when to prefer this tool, but it does not explicitly mention alternatives or 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description carries the burden. It adds behavior about Manhattan routing and the fact that it combines internal steps, but it does not disclose potential side effects like modifying the schematic file, creating duplicate wires, or failure conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences plus a structured Args block. It front-loads the purpose, uses minimal words, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (true), the description need not explain return values. It covers purpose, composite behavior, and all parameters. It lacks mention of error handling or constraints, but overall it is complete enough for a composite tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description's Args section fully explains every parameter with examples (e.g., ref1: 'First component reference (e.g. "U1")') and notes that schematic_path is optional with a default behavior. This fully compensates for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Connect two component pins with Manhattan (L-shaped) wire routing.' It clearly states what the tool does and distinguishes it from siblings like add_wires by emphasizing the L-shaped routing and composite nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The line 'Combines get_pin_positions + coordinate math + add_wires into one call' provides clear context that this tool is for high-level pin-to-pin connections using refs and pin names. While it implies when to use it, it does not explicitly name alternatives 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about the schematic_path default behavior and the pin/label matching feature, but does not disclose additional behavioral traits like return format or error conditions. This aligns with the calibration example where annotations carry the safety burden and the description adds modest context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a one-sentence purpose and a clean parameter list. It front-loads the main action and provides exactly the necessary details without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with two parameters, a read-only annotation, and an existing output schema, the description is adequate. It clearly states what the tool does and explains both parameters. The only gap is the lack of explicit usage exclusions, but the presence of an output schema and annotations reduces the burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does 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 each parameter: 'sheet_uuid: UUID of the sheet' and 'schematic_path: Path to parent .kicad_sch. Optional; omit to use the configured default.' This adds meaning beyond the schema's titles and default value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get detailed info' with a clear resource 'hierarchical sheet' and adds the distinctive feature 'including pin/label matching'. This distinguishes it from sibling tools like get_schematic_summary or list_schematic_sheets, which have different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when detailed hierarchical sheet info with pin/label matching is needed) but does not explicitly name alternatives or exclusions. Since the context is clear and the tool's unique purpose is stated, it earns a 4 rather than a 3.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that the operation is read-only, idempotent, and non-destructive. The description adds minimal extra behavioral context beyond the operation itself (e.g., the optional path resolution). It does not contradict annotations, but it doesn't significantly deepen the behavioral model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first states the core action, and the second explains the only parameter. Every word earns its place, with no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one optional parameter and an existing output schema, the description covers the operation, the parameter semantics, and the default behavior. It doesn't need to explain return values since an output schema is present, making it fully sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 the schematic_path parameter: its file type (.kicad_sch), its optionality, and the configured-default fallback behavior. This adds meaningful value beyond the schema's default-value field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the specific resource ('global labels in the schematic'), which precisely distinguishes it from sibling tools like list_schematic_labels and list_schematic_hierarchical_labels. The use of 'global' narrows the scope unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (to list global labels) and explains the optional path parameter with its default behavior. However, it does not explicitly mention alternatives or exclusions, leaving the comparison to siblings implicit in the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already indicates this operation is destructive. The description adds minor behavioral context by noting pcb_path is optional, but does not elaborate on side effects or error conditions (e.g., footprint not found). Given the annotation covers the main safety concern, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and well-structured, with a one-sentence summary followed by an Args section. Every sentence adds value without extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive tool with only two parameters and an output schema present, the description is adequately complete. It covers the essential usage and arguments, though it omits potential edge-case behavior like error handling for missing footprints. Given the low complexity, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides concrete semantics beyond the schema for both parameters: 'reference' is explained with an example ('R1'), and 'pcb_path' is described as an optional path with a default behavior. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Remove a footprint by reference designator', specifying the action (remove), the resource (footprint), and the key parameter (reference designator). This distinguishes it from sibling operations like remove_component or remove_label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the usage context clear: it targets PCB footprints with a reference designator, and mentions the optional pcb_path for specifying the file. It does not explicitly contrast with alternatives like remove_component, but the context is sufficiently clear for a single-purpose tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false (readOnlyHint=false, destructiveHint=false), so the description must carry the behavioral burden. It does disclose auto-selection and auto-detection behaviors, but it does not explicitly state that the PCB file is modified or saved, nor does it mention any side effects like overwriting existing vias or requiring an existing footprint. This is moderately transparent but has gaps 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a well-structured docstring with a one-line summary followed by a concise parameter list. Every line adds value—there is no fluff or repetition. The most important phrase ('Add a grid of thermal vias under a footprint pad') is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters (1 required), the description covers all of them with sufficient detail. It also explains conditional behavior (auto-selection, auto-detection, optional path). Since an output schema exists, return values need not be described. The description is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description is the sole source of parameter meaning. It explains every parameter with examples and defaults (e.g., 'Pad number to center vias on. If empty, auto-selects largest SMD pad.'). This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'Add a grid of thermal vias under a footprint pad.' This clearly distinguishes it from sibling tools like add_via (which adds a single via) and place_footprint. The purpose is unambiguous and directly tied to the tool's name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: 'under a footprint pad' and describes specific behaviors like auto-selecting the largest SMD pad and auto-detecting the net. However, it does not explicitly mention when to prefer this over alternatives (e.g., add_via for individual vias) or any exclusions. Since the context is clear but alternatives are not discussed, a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines3/5Does 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.
- Behavior4/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and readOnly=false; the description adds crucial nuance by specifying that it creates a new file and does NOT modify the original hierarchy. It also mentions offset positioning, giving an agent accurate expectations for the output layout. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a one-sentence summary, a brief merge explanation, a safety note, then a clear Args list. Every line earns its place with no fluff, maintaining high readability and quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema, the description covers the essential behavior, file creation side effect, and both parameters. It could mention potential overwrite behavior of output_path, but the output schema likely covers return details. Overall, the description is sufficiently complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining each parameter's purpose (schematic_path as the root file, output_path as the destination) and clarifies optionality and defaults. This adds meaningful context that the bare schema property names lack, making parameter usage clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Flatten a hierarchical schematic into a single sheet') with the resource (.kicad_sch hierarchy) and differentiates from siblings like list_schematic_sheets or add_hierarchical_sheet by the flattening intent. The verb 'flatten' precisely captures the operation, making it distinguishable from other schematic tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on the operation's effect (merging child sheets, creating a new file) and the key caveat that the original is untouched. It doesn't explicitly name alternative tools, but the scope is well-defined and prerequisite-free, which makes usage clear enough for an agent without requiring exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds specific behavioral context by listing the summary fields, which is valuable beyond what annotations provide, though it does not mention error handling or file-not-found behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first front-loads the purpose, the second clearly documents the argument. No redundant wording, every element serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema (which the description does not need to detail), the description is complete. It specifies what the tool returns and how to invoke it, and the annotations cover the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (pcb_path has no description in schema). The description compensates fully by explaining the parameter is a path to a .kicad_pcb file, optional, and with a configured default. This exceeds the baseline of 4 for 0 params because it adds meaningful semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 ('Get') and resource ('board summary'), and enumerates the exact fields returned (footprint count, trace count, net count, thickness). This distinguishes it from sibling listing tools like list_pcb_footprints or get_schematic_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides parameter usage guidance (pcb_path optional, default behavior) but does not explicitly compare this tool to alternatives or state when it should be preferred over other board-level tools. The intended use is implied but not clearly delineated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds that coordinates are in board space and that pcb_path is optional with a default config, giving useful 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct with a front-loaded purpose statement and an Args block. No extraneous information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema available, the description does not need to explain return values. It adequately covers the tool's purpose, parameters, and key behavioral details, making it complete for this simple read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description documents both parameters clearly: reference is a footprint designator, and pcb_path is an optional file path with a default behavior. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear action ('Get') and a precise resource ('board-coordinate bounding box of a placed footprint'), distinguishing it from related tools like get_footprint_pads or list_pcb_footprints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for obtaining a footprint's bounding box, but it does not explicitly mention when to prefer this tool over alternatives or provide exclusions. No sibling tool comparisons are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds context about the scanning and tracing steps, enriching the agent's understanding without contradicting any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a single-sentence purpose followed by a neat Args list. Every word earns its place, and it avoids unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully captures the tool's operation and parameters, while the existing output schema covers return values. For a straightforward read-only query tool, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates with a clear Args section. It explains label_text with examples ('VCC', 'GND') and notes schematic_path as optional with default behavior, adding meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Find all component pins connected to a net label', providing a specific verb and resource. It further details the method by stating it scans labels, traces wires, and identifies pins, which distinguishes it from sibling tools like list_schematic_labels or get_pin_positions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the purpose: use when you need to find pins connected to a net label. However, there is no explicit guidance on when not to use it or mention of alternatives like trace_hierarchical_net for cross-sheet net tracing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond this: the schematic_path is optional and omitting it uses a configured default, and the tool specifically operates on the root schematic. However, it does not describe edge cases or return format, though an output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single purpose sentence followed by a focused Args section. It is front-loaded with the main verb and resource, and every sentence earns its place without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, read-only annotations, and an output schema), the description covers all essential aspects: purpose, parameter semantics, and root-schematic scope. There is no notable gap for the intended complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no description for schematic_path (0% coverage). The description's Args section fully compensates by explaining the path format (.kicad_sch), its optionality, and the behavior when omitted (uses configured default). This gives clear meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('List all symbol instances') and the specific resource ('root schematic's symbolInstances table'). This distinguishes it from sibling tools like list_schematic_components by pinpointing the exact data table and root scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly mention when to use this tool versus alternatives, nor does it state any exclusions (e.g., 'only works on root schematic; for sub-sheets use X'). Usage is implied by the purpose, but no comparative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no further behavioral context, such as side effects or exclusions, beyond restating the listing scope. This matches the baseline for a tool where annotations carry the transparency burden and the description adds no extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one declarative sentence plus a short arg explanation. Every word adds value, and the structure cleanly separates the purpose from parameter details. This is appropriate for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one optional parameter, the description is complete. It states exactly what is returned (traces and vias), explains the default behavior for the missing argument, and an output schema exists to define the return structure. No missing context prevents correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only provides a title and default for pcb_path, with 0% description coverage. The description compensates fully: it explains that pcb_path is 'Path to .kicad_pcb file' and clarifies it is optional, with behavior when omitted: 'omit to use the configured default.' This adds meaningful semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'List all trace segments and vias on the PCB.' This uses a specific verb ('List') and resource ('trace segments and vias'), and the tool name 'list_pcb_traces' directly corresponds. It is distinct from sibling tools like list_pcb_footprints or list_pcb_nets, which list other PCB elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by specifying what is listed ('all trace segments and vias') and the optional pcb_path parameter. It does not explicitly mention alternatives or situations where a different list tool should be used, but for a simple read-only list operation, the intended usage is obvious. A 5 would require explicit alternatives or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=True, idempotent=True, and destructive=False. The description adds behavioral context by specifying the result scope ('all junctions') and explaining that omitting schematic_path uses a configured default, which goes beyond the schema's empty default string.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one main sentence plus a compact Args block. Every word adds value, no fluff, and the primary action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter list tool, the description fully explains the operation and the parameter. With annotations covering safety and an output schema present, no further context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates by documenting the only parameter: it is the path to a .kicad_sch file, is optional, and omitting it uses a configured default. This provides meaningful semantics beyond the bare schema property.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('all junctions in the schematic'), clearly distinguishing it from mutation siblings like add_junctions and remove_junction. The scope ('all junctions') and file reference (schematic_path) make the operation unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a read-only listing operation but does not explicitly state when to use it versus alternatives. No exclusions, alternatives, or conditions are mentioned, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotent and non-destructive hints, and the description adds meaningful behavior: it requires kicad-cli, auto-redirects to root schematic, and references an ERC report file via output_dir. It does not fully describe report-file lifecycle, but the added context is substantive beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short logical blocks—action/dependency/behavior, then args—front-load the key information with no filler. Every sentence earns its place, and the Args section is scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, return-value details are not required; description covers dependency, root redirection, and all parameters. Minor omission of explicit alternative-tool guidance prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no descriptions (0% coverage), so the Args section must carry the weight; it does by explaining each parameter's file format, optionality, and default behavior. The descriptions are sufficient but could note interactions (e.g., when project_path is needed) for a higher score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence uses a specific verb-resource pair ('List unconnected pins') and adds the method ('by running ERC and filtering results'), which clearly separates it from full-ERC and no-connect-list siblings. The name and description align tightly, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states the kicad-cli prerequisite and explains the automatic root-schematic redirection with rationale, giving practical context for sub-sheet usage. It does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without any safety hints from annotations (readOnly=false, destructive=false), the description carries the burden. It discloses key behavioral traits: the difference between a real footprint and a pad-less marker, the copying from library exactly as KiCad, and that the older marker behavior is kept for placeholder callers. This goes well 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose, followed by the crucial real-vs-marker distinction, then a structured argument list. Each sentence adds information, though the argument list is somewhat long; still, it is efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with no schema descriptions and minimal annotations, the description covers the core behaviors, parameter semantics, and points to list_lib_footprints. It could add what happens on error (e.g., library not found) but given the output schema exists and sibling tools are listed, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no property descriptions), so the description fully compensates. It explains every parameter with examples and conditional behavior: library optional for marker, footprint required when library given, pcb_path defaults, layer options. This adds meaning the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Place a footprint on the PCB.' It clearly distinguishes between placing a real footprint (with pads and silkscreen) and a marker, which sets it apart from related tools like place_component (schematic) and move_footprint (existing footprints).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool with a library/footprint vs. without, and directs users to list_lib_footprints for prerequisites. It does not explicitly mention when not to use it versus schematic placement tools, but the 'on the PCB' wording and sibling context make the boundary clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the destructive nature is known. The description adds no additional behavioral context (e.g., irreversibility, side effects on connected nets, or behavior if the reference doesn't exist). It is consistent with annotations, so no contradiction, but it does not go beyond what annotations and the verb 'Remove' imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a neatly formatted Args list. Every sentence is purposeful, information is front-loaded, and there is no fluff. It earns a perfect score for conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, 1 required) and the existence of an output schema, the description fully covers the purpose, parameters, and file context. The optional schematic_path behavior is clearly noted. No meaningful gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions, but the description's Args section explains both parameters clearly: 'reference' with an example ('U2') and 'schematic_path' with its purpose and optional behavior. This fully compensates for the schema's lack of descriptions and adds practical detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Remove a component') and the specific method ('by reference designator'), which distinguishes it from sibling tools like remove_footprint (PCB) or remove_hierarchical_label. The resource and action are immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by specifying the schematic file path and the reference designator, implying it is for schematic components. It doesn't explicitly mention alternatives, but the naming and parameters make the appropriate use case evident. No exclusion criteria are given, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
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.
Conciseness5/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details: it accounts for rotation/mirror and describes the default schematic_path behavior. It does not cover missing-component errors, but the safety profile is well covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and followed by a minimal Arg list. Every sentence contributes useful information with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool with an output schema and strong annotations, the description is nearly complete. It covers the essential purpose, rotation/mirror handling, and parameter semantics. It lacks explicit error-case or sibling-tool guidance, but these are minor given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), but the description's Args section fully explains both parameters: reference format ('U1', 'R1') and schematic_path's optionality and default behavior. This adds meaning well beyond the raw schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a specific resource ('absolute pin positions for a placed component'), and adds a crucial qualifier ('accounts for rotation/mirror') that distinguishes it from sibling tools like get_symbol_pins. It unambiguously conveys what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for placed components and notes the optional schematic_path behavior. It does not explicitly name alternatives or state when not to use it, but the use case is evident enough for a read tool. This matches 'clear context, no exclusions'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by specifying the exact content returned ('build details and library versions'), which is behavioral context beyond the annotations. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is immediately informative and front-loaded with the verb and resource. Every word contributes meaning; there is no fluff or redundancy. It is appropriately sized for a simple no-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, read-only, idempotent) and the presence of an output schema, the description is fully adequate. It explains the purpose and scope of the returned information without needing to document parameters or side effects. The annotations and output schema cover the remaining context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema description coverage is trivially 100%. The baseline for 0 parameters is 4, and the description properly focuses on what the tool does rather than needing to explain parameter inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and clearly identifies the resource as 'KiCad version information'. It further specifies the scope with 'build details and library versions', distinguishing it from all sibling tools which perform other actions. There is no ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: to retrieve version information from KiCad. It does not explicitly state when NOT to use it, but the absence of parameters and the read-only nature make it self-evident that this is a safe, general-purpose query tool. Clear context, though no explicit exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds important behavioral context: it does not remove vias, and it requires at least one filter. It also specifies units (mm) for the bounding box parameters. However, it does not discuss irreversibility or file saving implications, which the destructive annotation partially covers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It opens with a clear one-sentence purpose, states the filter requirement, then presents a compact Args list. There is no redundant or unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters and a schema coverage of 0%, the description covers all inputs thoroughly. It also includes a constraint and notes about vias. The presence of an output schema handles return value documentation. Minor omissions include edge-case behavior (e.g., no matching traces), but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides zero descriptions for parameters (0% coverage). The description compensates fully with an Args section that explains each parameter: net_name, layer (with examples like 'F.Cu'), bounding box edges (in mm), and pcb_path (optional with default behavior). This completely addresses parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's function with a specific verb and resource: 'Remove trace segments matching the given filters.' It also explicitly notes 'Does not remove vias,' which differentiates it from other removal tools like remove_label, remove_wire, and remove_footprint that operate on different PCB elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by explaining the filters and stating 'At least one filter (net_name, layer, or bounding box) is required.' It also gives an exclusion ('Does not remove vias'), but it does not explicitly name alternative tools for handling vias or other objects, so it lacks explicit alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive (destructiveHint=true), and the description adds valuable behavior: 'Matches wires with endpoints within 0.1mm tolerance (in either order)'. This discloses the matching logic, which is beyond the annotations and helps predict tool behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-line purpose, a matching rule, a usage pointer, and a clear Args block. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (not shown), return format need not be described. The description covers the matching tolerance, the prerequisite listing, and the optional path parameter. It omits potential edge cases like no-match behavior, but for a targeted removal tool it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions in schema), so the description fully compensates. The Args block provides meaningful definitions for all parameters: x1/y1 as Start X/Y, x2/y2 as End X/Y, and schematic_path with its default behavior. This goes well beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Remove a wire segment by its endpoint coordinates' with a specific verb and resource, clearly distinguishing it from other remove_* tools (component, label, junction). It also adds matching tolerance and order flexibility, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to 'Use list_schematic_wires to get wire coordinates first', providing a clear prerequisite and workflow. It does not explicitly name alternatives or exclusions, but the specificity of the tool and the prerequisite make when-to-use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation safe (readOnlyHint=true, destructiveHint=false, idempotentHint=true), and the description adds behavioral detail by naming the exact checks performed. It does not contradict any annotation and provides useful context about what the tool inspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at about four sentences, front-loading the purpose and then listing specific checks. The parameter doc is integrated neatly, and there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has a single optional parameter, clear annotations, and an output schema (mentioned in context), the description adequately covers what the tool does and the scope of validation. It could elaborate on output format or prerequisites, but the output schema presumably covers return details; the description is sufficient as a summary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'schematic_path' is described in detail in the description: 'Path to root .kicad_sch file. Optional; omit to use the configured default.' This exceeds the schema, which only provides a title and default, compensating for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Validate hierarchical schematic for common issues.' This distinctly identifies the tool's purpose and differentiates it from sibling tools like 'validate_board' (PCB validation) and 'run_erc' (electrical rules check) by focusing on hierarchical schematic structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description enumerates specific categories of issues checked (orphaned labels/pins, direction mismatches, duplicate reference designators, etc.), which strongly implies the tool's use case—hierarchical schematic structural validation—without explicitly naming alternatives. This is clear context rather than vague guidance, though it stops short of stating when not to use it compared to 'run_erc' or 'validate_board'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the minimal annotations by disclosing key behaviors: 'one file write' (file modification), 'short stub and a shared net label' (how the wiring is done), and the auto_pwr_flag behavior ('Auto-place PWR_FLAG when net has power_in but no power_out'). This provides useful behavioral context. It does not mention failure modes or preexisting conditions, but the disclosed details are significant, so a 4 is warranted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured. It opens with a clear purpose, then a one-sentence behavioral summary, followed by a concise Args list. Every sentence adds value, no filler. The parameter explanations are front-loaded after the purpose, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all parameters and key behaviors, and an output schema exists (so return values are not needed). However, it leaves a slight ambiguity about whether the net label is created or must already exist. It also doesn't discuss what happens if pins are already wired, but given the tool's scope and the presence of an output schema, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description compensates excellently by explaining each parameter with examples, units, defaults, and behavior. It clarifies the pins dict format, gives example label text, lists direction options, specifies stub_length in mm with default, explains auto_pwr_flag's condition, and notes schematic_path is optional. This is far beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource phrase: 'Wire multiple component pins to the same net label.' This clearly differentiates from sibling tools like add_wires (which adds generic wires), add_label (which adds labels without wiring), and connect_pins (which likely connects pins without a net label). The method is clarified with 'Wires each pin with a short stub and a shared net label, one file write.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to connect multiple pins to a shared net label. It does not explicitly exclude alternatives or state 'use this instead of X,' but the purpose is evident. The one-file-write note also hints at efficiency, giving some usage context. There are no exclusions or alternative references, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the pin mapping (pin 1 to power_net, pin 2 to ground_net) and the method (stub wires + labels). It also notes that project_path is for sub-sheet instance tracking. Annotations are all false and offer no conflict; the description adds behavioral context beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear purpose statement followed by an Args list. It is dense but not verbose, with each line adding necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (11 parameters) and empty schema descriptions, the description covers the tool's behavior, all parameters, examples, and optional defaults. Output schema exists, so return value documentation is not needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no descriptions (0% coverage), but the description's Args section explains each parameter with examples (e.g., lib_id: 'C', reference: 'C5') and clarifies optional paths. This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'Place a decoupling capacitor and wire it to power/ground nets.' It clearly distinguishes from generic placement tools like place_component by specifying the decoupling cap and the wiring behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it: when a decoupling capacitor needs to be placed and connected to power/ground. However, it does not explicitly mention alternatives or when not to use it, such as when a generic placement is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness4/5Is 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.
Completeness4/5Given 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.
Parameters5/5Does 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.
Purpose5/5Does 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.
Usage Guidelines4/5Does 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by documenting that pcb_path is optional and that omitting it uses a configured default, which is beyond the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is minimal and front-loaded: a one-sentence purpose followed by a single parameter arg block. Zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool, the description covers purpose, parameter semantics, and the safety profile is covered by annotations. An output schema exists to describe return values, so no further explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides type and default for pcb_path with no description. The description compensates fully by explaining it is a path to a .kicad_pcb file, optional, and that omission uses a configured default. This is critical for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all footprints on the PCB', with a specific verb (list) and resource (footprints on the PCB). This distinguishes it from sibling tools like list_lib_footprints that list library footprints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context that this tool operates on PCB footprints rather than library footprints, but it does not explicitly mention alternatives or exclusions. The distinction is implicit via the phrase 'on the PCB' and the sibling tool list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint and idempotentHint, and the description aligns by using 'List.' The description adds behavioral detail about the optional pcb_path and the fallback to a configured default, which supplements the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences: a clear one-line purpose and a parameter explanation. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity, read-only listing tool, the description covers purpose, scope, parameter semantics, and default behavior. An output schema exists, so return details need not be in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully explains the single parameter: 'pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.' This compensates completely.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and a specific resource 'zones (copper and keepout) on the PCB,' clearly distinguishing it from sibling tools like add_copper_zone or fill_zones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes a clear context: it lists all zones on the PCB. It does not explicitly name alternatives or when-not-to-use conditions, but the scope is unambiguous. The read-only nature and sibling lineage further clarify appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent, and the description aligns with them. It adds useful context about listing 'all' labels and that schematic_path can be omitted to use a configured default, without any contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one action sentence plus a minimal Args block. No wasted words; it is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with one optional parameter, an output schema, and safety annotations, the description provides all needed context. It clarifies the scope and the optional path behavior without unnecessary detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides an empty default and no property description, but the description thoroughly explains schematic_path's purpose, optionality, and default behavior. This fully compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact action ('List') and resource ('all hierarchical labels in the schematic'), which clearly distinguishes it from sibling tools like list_schematic_labels or list_schematic_global_labels. The scope 'all' adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this tool when you need hierarchical labels. It does not explicitly mention alternatives or exclusions, but the domain-specific term 'hierarchical' and sibling names provide enough disambiguation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior, so the description adds value by explaining sentinel semantics: empty strings for new_text/new_shape and None for new_x/new_y mean 'keep current'. It also discloses that schematic_path can be omitted to use a default. This is beyond the annotations and helps predict tool behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a single-purpose sentence followed by an Args block. Each line adds unique meaning with no redundancy, and the most important use-case information appears first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters and an output schema present, the description adequately covers all parameter behaviors including defaults and lookup mechanics. It does not need to explain return values due to the output schema, and no major operational aspects (like matching, disambiguation, or optionality) are omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining every parameter's purpose: text is used for lookup, new_text/new_shape use empty string as 'keep current', new_x/new_y use None as 'keep current', and uuid is for disambiguation. These are critical semantics not inferable from the schema types alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Modify an existing hierarchical label', specifying the verb (modify) and the resource (existing hierarchical label). This distinguishes it from siblings like add_hierarchical_label or remove_hierarchical_label, and clarifies the scope as an existing entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by specifying the operation is for existing labels and includes parameter-level instructions such as 'Current label text to find' and 'empty = keep current'. It does not explicitly list alternative tools or exclusions, but the guidance on prerequisite input (text) and optional overrides is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior (destructiveHint=true), and the description adds valuable context: the iterative removal process and the precise definition of a dangling segment (endpoint not connecting to pad, via, or another trace). It does not contradict annotations and goes beyond what structured metadata conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It front-loads the main purpose, then explains the algorithm, and ends with parameter documentation. Every sentence adds value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (one optional parameter, output schema exists, annotations cover destructive behavior), the description is complete. It explains what, why, how (iterative), and the argument meaning. No gaps remain for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does 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 for the single parameter. It fully explains pcb_path: a path to a .kicad_pcb file, optional, with a default behavior ('omit to use the configured default'). This is clear and sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Detect and remove trace segments with unconnected endpoints.' It uses a specific verb ('remove') and resource ('dangling tracks'), and distinguishes itself from sibling tools like remove_traces by focusing on unconnected endpoints. The iterative behavior and dangling criterion add precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (to clean up dangling segments) but does not explicitly mention alternatives or exclusions. It says what the tool does, which implies its use case, but lacks direct comparison to other trace-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive (destructiveHint=true), so the mutation is understood. The description adds valuable behavior: it removes every no-connect at the pin's position, not just one, which is important for users who may have stacked duplicates. This goes beyond what annotations or schema convey, and no contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five lines: a front-loaded action sentence, a clarifying sentence about duplicate behavior, then a clean Args section. Every sentence earns its place with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 params, destructive nature, 0% schema coverage), the description is complete: it states the action, duplicate semantics, parameter details, and default path behavior. An output schema exists, so return values are already defined; no further explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining each argument: reference examples 'U2', pin_name examples 'NC' or '3', and schematic_path default behavior when omitted. This provides meaning that the schema's bare property titles lack.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description begins with 'Remove no-connect flag(s) from a component pin' – a specific verb and resource. It clearly distinguishes from siblings like no_connect_pin (adds flags) and list_schematic_no_connects (lists flags) by focusing on removal. Additional detail about stacked duplicates clarifies the exact scope of removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this tool to remove no-connect flags from a pin, and notes that repeated no_connect_pin calls stack duplicates, which this clears in one go. It does not explicitly name alternatives or when-not cases, but the implied usage compared to sibling tools is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive behavior. The description adds valuable context beyond annotations: auto-redirect to root schematic, returns JSON report, and the existence of a report file via output_dir. It also explains the purpose of the auto-redirect (avoiding false positives). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded. The first sentence states the purpose, followed by a key behavior note, return type, and an Arg list. Every sentence earns its place, with no redundant fluff. The 'Args:' section is necessary given the schema's lack of descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, key behavior (auto-redirect), output format, and all parameters with defaults. With an output schema available, the need to detail return values is reduced. It adequately addresses the sub-sheet use case, making it complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description fully compensates by clearly defining all three parameters (schematic_path, output_dir, project_path), including their defaults and specific roles. Notably, project_path is explained as 'for explicit root resolution', which adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear, specific verb phrase: 'Run Electrical Rules Check (ERC) on a schematic.' It identifies the resource (schematic) and the action (running ERC). The addition about auto-redirecting to root schematic distinguishes it from other schematic analysis tools and clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool, especially noting its behavior on sub-sheets ('Auto-redirects to root schematic... to avoid false positives'). It does not explicitly name alternative tools or exclusion criteria, but the context is sufficiently clear for selecting ERC over similar tools like run_drc.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is exceptionally transparent about behavior: it rewrites every footprint, uses a copy with atomic writes, only writes changed files, creates a backup, and notes that the library is not a transaction. This goes well beyond the destructiveHint annotation, providing context about safety and side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but well-structured, with the purpose upfront and explanatory paragraphs. It is longer than minimal but every sentence adds valuable context about safety and behavior. It is concise relative to the complexity of the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all critical context for a destructive library operation: scope, backup, atomicity, partial failure, and alternatives. With an output schema present, no return-value details are needed. It is complete and leaves no major gaps for an agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that footprint_path is a directory path and mentions a default, but it contradicts the schema which marks it as required (the description says 'Optional'). This inconsistency reduces clarity. Since schema coverage is 0%, the description needed to compensate but introduced a contradiction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Upgrade a footprint library to current KiCad format.' It specifies the verb (upgrade) and resource (footprint library), and distinguishes it from sibling tools like 'upgrade_symbol_lib' by explicitly mentioning footprint library.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: it takes a library directory, rejects a single .kicad_mod path, and advises version control as a better alternative for important libraries. It clearly explains when to use this tool and when not to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description supports these by noting it only reports a result ('reports ok') without asserting side effects. The description adds meaningful context about the origin-point semantics and why rotation is absent—information not present in the annotations. It gives an example of an edge case (body overlaps keep-out but origin doesn't) which improves the agent's understanding of potential false negative/positive behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise—a single paragraph plus a short bullet list of parameters with one-line descriptions each. It front-loads the main purpose in the first sentence, then uses whitespace and structure for readability. Every sentence adds value, and the note about rotation is relevant to interpretation without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only check with 4 parameters and a boolean-like result, the description is highly complete. It explains the input semantics, the return behavior (reports ok), and edge cases (origin check). The output schema exists, so the description need not explain return values. The description covers the necessary context—origin-based checks, why rotation is not needed, and how to skip pcb_path—leaving no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the parameter-documentation burden. The description explains the meaning of x/y as 'proposed X position' and 'proposed Y position,' reference as 'Footprint reference designator,' and provides optional behavior for pcb_path. It adds semantic value by clarifying these are the positions where the footprint would be placed, but it could provide more detail about coordinate space or allowed units.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: 'Check if placing/moving a footprint to (x, y) would violate constraints.' It uses a specific verb and resource, and the note about the origin point distinguishes this from other footprint-related tools. The tool title and description unambiguously identify what the tool does, differentiating it from sibling tools like check_footprint_bounds or validate_board.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the check is on the footprint's origin, which clarifies an important use-case nuance, and the note about the lack of a rotation parameter explicitly explains why rotation isn't present. While it doesn't explicitly say 'use this instead of X,' the description implies the tool's specific role in placement validation versus other placement tools. It gives context on when the check might return 'ok' even if the footprint body overlaps a keep-out, but it could be more explicit about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the all-false annotations by disclosing a critical guarantee: 'the file that reaches the disk is the original with its zones' fills replaced and every other byte untouched,' explicitly listing what is preserved ('not its format version, not its layer names, not the constructs pcbnew does not model'). It also surfaces the pcbnew bindings dependency. No annotation contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is model-like in structure: a crisp front-loaded subject-verb-object opening followed by a tight three-sentence behavioral paragraph, a one-line dependency note, and a labeled Args section. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-optional-parameter tool with an output schema present, the description thoroughly covers what the tool does, how its side effects are bounded, what environment it requires, and how the parameter works. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description compensates by documenting pcb_path with its purpose ('Path to .kicad_pcb file'), optionality, and fallback semantics ('omit to use the configured default'). It adds meaning beyond the bare schema but does not go into extended detail beyond the single param.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening line, "Fill all copper zones on the board using pcbnew's zone filler," uses a specific verb+resource+mechanism structure. It clearly differentiates this tool from sibling read-only/analysis tools and from zone creation tools like add_copper_zone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about the operation and its non-destructive nature via the explanation that 'pcbnew computes the fill; this server writes it.' However, it never explicitly enumerates when-not-to-use scenarios or names alternatives, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses destructive nature (delete_child_file behavior) and error handling, adding context beyond annotations. It explains conditions for file deletion and outputs UUIDs on ambiguity, providing full behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two clear paragraphs. The overview front-loads the purpose, and the Args section is structured. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, identification, error handling, and file deletion. It does not explicitly state what happens if the sheet does not exist, but the output schema covers return values. Minor gap but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description's Args block fully explains each parameter's purpose and behavior. It adds meaning beyond the schema, especially for 'delete_child_file' with its conditional deletion note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it removes a hierarchical sheet block from a parent schematic, with a specific verb and resource. It distinguishes itself from siblings like 'add_hierarchical_sheet' and 'modify_hierarchical_sheet' by the action type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains identification methods (name, uuid) and disambiguation behavior when multiple sheets match. It does not explicitly state when not to use or suggest alternatives, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With all annotation hints false, the description carries the full burden and does well. It discloses that missing properties are created, that Reference/Value/Footprint are mirrored into symbol instances and the root symbol_instances table, and that renaming happens by setting key='Reference'. It also warns about the .kicad_pro dependency for root-table updates, which is valuable behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: the core action is front-loaded, followed by the important side-effect paragraph, then a compact Args list. Every sentence adds information relevant to correct invocation, and the length is justified by the mirrored-table behavior it explains.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter property setter with an output schema, the description covers the operation, creation semantics, cross-table effects, project-file dependency, and parameter meanings. It does not need to describe return values because an output schema exists, and it provides enough detail for an agent to select and invoke the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The Args block adds concrete semantics for all four parameters with examples ('R1', 'MPN', 'Tolerance', 'Value') and notes that schematic_path is optional. It does not enumerate every possible property key or value-formatting rule, but for an open-ended property setter that is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource action: 'Set any property on a placed component, or rename it.' It also clarifies that missing properties are created, and the reference to renaming via key='Reference' distinguishes it from generic setters. The tool is clearly differentiated from sibling placement/label/PCB tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: it modifies placed component properties and explains the difference between working with a .kicad_pro versus a loose .kicad_sch. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only, idempotent, and non-destructive. The description adds useful context beyond those annotations: the actual layer set is board-dependent and layer names may be renamed. This contextualizes the tool's behavior without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: two functional sentences plus a clear Args line. Every sentence contributes either purpose, usage guidance, or parameter meaning with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only tool with a corresponding output schema and strong annotations, the description is fully sufficient. It covers purpose, behavior variability, prerequisite usage, and parameter semantics, leaving no material gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides a default string for pcb_path, but the description fully explains the parameter semantics: it is a path to a .kicad_pcb file, optional, and can be omitted to use the configured default. This adds meaning well beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly starts with 'List all layers defined in the PCB stackup' and enumerates the layer categories, making the resource and action unambiguous. It also distinguishes itself from sibling list tools such as list_pcb_traces and list_pcb_nets by targeting the stackup layer set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs the agent to call this tool before any tool that takes a layer name, and justifies this with per-board valid sets and common layer renames. This gives concrete when-to-use guidance and explains the dependency relationship.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses critical behavioral details: it warns that without filters it removes ALL texts with matching content, and specifies the 0.1mm positional tolerance. This is exactly the kind of context that helps an agent understand the tool's destructiveness and matching logic.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, a behavior explanation with conditional logic, and a concise Args list. Every sentence adds value, and the most important information (remove all vs filtered) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and conditional behavior, the description covers all parameters, the positional filtering logic, and the optional default for schematic_path. An output schema exists, so return values need not be described, and the description is sufficient for an agent to invoke the tool safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description's Args section explains each parameter: text is the content to match, x/y are optional position filters, and schematic_path is the path with a default. It also adds the positional tolerance in the prose, providing meaning beyond the schema's bare types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Remove text annotation(s) by content, optionally filtered by position.' This uses a specific verb and resource, and distinguishes it from sibling tools like remove_label by targeting 'text annotations' specifically. It also explains the conditional filtering behavior, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: it can either remove all texts with matching content or only those matching both content and position. However, it does not explicitly mention alternatives or when not to use it (e.g., for labels use remove_label), so it falls short of a 5 but is still well above minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it edits the .kicad_pro project file alongside the board, a key side effect, and explicitly states that pcbnew is not required. It also explains that None parameters use defaults. These details add significant context beyond the sparse annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a well-organized docstring that front-loads purpose, then provides behavior and an Args breakdown. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, behavior, file modifications, prerequisites (no pcbnew), and all parameters. Since an output schema exists, return values are already covered. This is complete for a tool with moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden. The Args section explains all 7 parameters, including units (mm), the meaning of None (use default), and the pcb_path default behavior. This adds clear semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Create or update a net class with design rules and assign nets,' which clearly states the verb and resource. It uniquely identifies the tool's purpose among siblings by focusing on net class management, which no other sibling tool handles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool (to create/update net classes and assign nets) and notes that pcbnew is not required, which is a practical guideline. However, it does not explicitly mention alternatives or when not to use, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
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.
Conciseness5/5Is 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.
Completeness5/5Given 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.
Parameters4/5Does 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.
Purpose5/5Does 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.
Usage Guidelines5/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply false hints, so the description carries the full behavioral burden — and it does so richly: it covers side effects (creates .kicad_pcb if missing), placement behavior (grid cluster), deletion policy (only stale unlocked, locked never removed), zone handling, byte-preserving writes, and the exact net-naming behavior. It even notes what it no longer depends on (pcnew Python bindings).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and front-loaded with the essential one-sentence summary, then elaborates with necessary caveats and parameter explanations. Some details pushed the text into a long unformatted paragraph, but every sentence earns its place given the tool's complexity, so a high score is warranted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex PCB-update tool, the description covers the full lifecycle: purpose, first-run creation, matching/position behavior, deletion semantics, zone refill follow-up, net-naming conventions, dependencies, and byte-level write guarantees. The presence of an output schema means not explaining the return shape is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema_description_coverage, the description must fully compensate, and it does: every parameter gets semantic meaning (e.g., schematic_path is a .kicad_sch file, optional, falls back to configured default; pcb_path is created if missing; project_path resolves root/sub-sheets). It also adds the 'unlocked' qualifier to delete_stale, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb+resource pairing ('Update the PCB from the schematic') and expands it with a concrete mechanism: exports the netlist, loads footprints, and binds every pad to a net. It also distinguishes itself from related tools by explicitly calling out fill_zones and list_pcb_nets as follow-ups, and by stating exactly what it does and does not do.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: 'Zones are NOT refilled: run fill_zones afterward', 'read them with list_pcb_nets', removal of stale footprints happens only via delete_stale, and it states the prerequisite 'Requires kicad-cli'. These explicit alternates and follow-up instructions make it clear when this tool should be used and what to do instead or next.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond destructiveHint=true by specifying that without positional filters ALL matching labels are removed and that matching uses 0.1mm tolerance. This discloses the actual destructive scope and avoids surprises. It does not contradict 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and logically structured: behavior first, then conditional rules, then a usage hint, then parameter definitions. No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive filter/removal tool, it covers the action, positional edge cases, an alternative for moving labels, and all parameter meanings. The output schema handles return values, so no additional return documentation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the Args section defines every parameter: text as match string, x/y as optional position filters, and schematic_path with default behavior. It adds semantics such as 'within 0.1mm tolerance' that the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') and names the exact resource ('net label(s) or global label(s) by text'), clearly differentiating it from sibling tools like remove_hierarchical_label. It also mentions optional position filtering, giving a precise scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly describes conditional behavior: when x/y are provided, only matching labels within tolerance are removed; otherwise all matching-text labels are removed. It provides an alternative workflow for moving global labels via add_global_label, and the scope (net/global vs hierarchical) is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ProductOfAmerica/mcp-server-kicad'
If you have feedback or need assistance with the MCP directory API, please join our Discord server