Lint Schematic Cosmetic

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

The annotations already flag destructiveHint=true and readOnly=false. The description adds valuable behavioral detail beyond those annotations: raw-text edits never move anchors, are netlist-safe, leave non-pin labels untouched, and are rotation/mirror aware. This is exactly the kind of context the agent needs.

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

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

The description is three dense sentences, front-loaded with the key safety guarantee, then methodically explains each pass. Every sentence earns its place with no filler or repetition.

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

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

Given the 3-parameter schema, the presence of an output schema, and the complexity of the two passes, the description is complete. It covers both passes' behavior, safety constraints, and relationship to a sibling tool; defaults and return values are left to the schema, which is appropriate.

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

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

Even though the schema covers 100% of parameters, the description gives deep meaning to the two passes that the bare enum values do not convey, including the exact directive added by hide_pin_names and the orientation/justify behavior of orient_labels. This far exceeds the schema's baseline.

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

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

The description clearly states the tool performs 'netlist-safe cosmetic cleanup' on .kicad_sch files via raw-text edits, and enumerates two specific passes (hide_pin_names and orient_labels). It also distinguishes itself from the sibling autoplace_schematic_fields by noting it complements that tool.

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

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

It gives concrete context for when each pass is useful (e.g., hide_pin_names for label-driven schematics) and explicitly mentions autoplace_schematic_fields as a complementary tool. However, it does not provide explicit when-not-to-use exclusions or alternatives beyond that single complement reference.

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