Skip to main content
Glama
cadcraft-electrical-mcp

cadcraft-electrical-mcp

sheet_add

Add sheets to an industrial electrical project for power/control circuits, PLC I/O, network topology, terminal plans, and cabinet layouts, defining circuit paths and rails for automatic documentation.

Instructions

Add a sheet definition. Kinds:

  • power / control: list of current paths. Each path: supply rails (one per pole, e.g. ['L1','L2','L3'] or ['24V']), series elements [{device, symbol?, terminals?, label?}], optional return_rail ('0V', 'N') and pe. Symbols/terminals default from the device kind (coil A1-A2, contacts 13-14/21-22..., poles 1-2/3-4/5-6). Use symbol 'contact_no'/'contact_nc' to draw a relay/contactor contact; cross references are automatic. Long sheets paginate.

  • plc_io: plc tag (+ optional io_kinds); draws every channel assigned with plc_io_assign.

  • network: topology of all network links. * cover / terminal_plan / cabinet_layout: automatic.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "kind": "<kind>",
      "title": "<title>"
    },
    "name": "sheet_add"
  }
}

Input Schema

NameRequiredDescriptionDefault
plcNo
kindYes
noteNo
pathsNo
titleYes
io_kindsNo
positionNo
sheet_idNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already declare the mutation profile (not read-only, not destructive, not idempotent, closed-world), so the description is free to add operational detail — which it does: symbols and terminals are auto-derived from device kind with IEC 60947 numbering, cross references are automatic, and long sheets paginate. What it does not disclose is whether `position`/`sheet_id` control insertion ordering or whether an existing sheet is ever overwritten.

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

Conciseness4/5

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

Front-loaded with the core action and then structured by kind, which mirrors how the agent must pick a branch. It is dense but mostly earns its length; the layout is a little cramped (kinds and bullets collapsed into a single block), which slightly hurts scannability.

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

Completeness3/5

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

An output schema exists, so return values need no explanation, and the power/control path model is well covered. Gaps remain for an 8-parameter mutation tool: the role of `position` and `sheet_id`, whether `paths` is required for power/control, and whether the target project must be open beforehand.

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

Parameters3/5

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

Top-level schema description coverage is 0%, so the description must compensate — and it does for `paths` (supply rails, series elements, return_rail, pe), `plc`/`io_kinds`, and default symbol/terminal behavior. It says nothing about `title`, `note`, `position`, or `sheet_id`, leaving half the parameters semantically unexplained outside the schema.

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

Purpose4/5

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

States a specific verb and resource ("Add a sheet definition") and enumerates the seven sheet kinds, so an agent knows what gets created. It distinguishes itself from plc_io_assign by stating that plc_io sheets draw channels already assigned there. However it never mentions sheet_add_paths, the closest sibling for adding circuits, leaving that boundary unstated.

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

Usage Guidelines3/5

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

The per-kind explanations imply which kind to choose (power/control need `paths`, plc_io needs `plc`, network/cover/terminal_plan/cabinet_layout are automatic), which is useful implied guidance. There is no explicit statement of when to use this tool versus sheet_add_paths or sheet_update, and no prerequisites (e.g. an open project, devices existing) beyond the passing note that a device must exist in the project.

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