Skip to content

ADR-0003: Export Tool Naming and Aliases

Status: Accepted Date: 2026-06-16 Deciders: @oaslananka

Context

A review flagged that the same export format appeared under multiple tool names (K3), risking agents picking the wrong tool and reviewers seeing an uncurated surface. Investigating the actual registered surface (the mcp.tool()(...) calls in src/kicad_mcp/tools/export.py) showed the duplication is narrower than the raw function inventory suggests:

  • The sch_export_* and pcb_export_* functions (e.g. sch_export_svg, pcb_export_glb) are internal helpers, not registered tools. Only the export_* wrappers are registered, so they are not agent-facing duplicates.
  • export_stepz exports KiCad's stpz (gzip-compressed STEP) format with a distinct --format/extension — a different output, not a duplicate of export_step.
  • pcb_export_3d_pdf (3D PDF) and pcb_export_stats (structured JSON stats) are the sole registered tool for their respective outputs; get_board_stats returns a human-readable text preview for a different purpose.

The one genuine case of two registered tools producing the same output is STEP: export_step and export_3d_step both emit board.step.

Decision

  1. The canonical naming convention for export tools is export_<format> — the dominant existing root. One canonical tool per output format.
  2. A genuine same-output duplicate is kept for backward compatibility as a deprecated alias through the central registrar src/kicad_mcp/tools/aliases.py (register_alias + notify_deprecated): the alias stays registered and functional, delegates to the canonical tool, logs a one-time deprecation warning, and is recorded in ALIASES.
  3. Applying this now: export_3d_step becomes a deprecated alias of export_step.
  4. export_stepz, pcb_export_3d_pdf, pcb_export_stats, and get_board_stats are not aliased — each is the only tool for a distinct output and was misread as a duplicate.

Consequences

  • Public tool names are not removed or silently renamed; deprecated names keep working and emit a one-time, structured deprecation log (work order rule 6).
  • New export tools must follow export_<format>; a new same-format duplicate must be registered via register_alias, not as a second canonical tool.
  • The alias registrar is reusable for future surface curation (e.g. the orphaned-tool cleanup in ADR-tracked Phase 1 work).

Verification

  • tests/unit/test_tool_registry_consistency.py (no cross-category name collisions) and tests/integration/test_tool_surface_snapshot.py stay green.
  • tests/integration/test_export_alias.py asserts export_3d_step is registered, is in ALIASES mapped to export_step, and delegates to the same output.
  • pnpm run docs:tools reflects the deprecated-alias docstring.