Skip to main content
Glama
cadcraft-electrical-mcp

cadcraft-electrical-mcp

device_remove

Destructive

Removes a device from an electrical project by tag. Fails when the device is still referenced, unless force is set to also delete those references.

Instructions

Remove a device. Fails if it is referenced unless force=true (then references are removed too).

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": {
      "tag": "<tag>"
    },
    "name": "device_remove"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagYes
forceNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds genuinely new behavior: the call can fail on referenced devices, and force=true performs a cascading removal of those references — a detail not present in any structured field. It omits permissions/auth requirements and does not elaborate on the non-idempotent hint.

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

Conciseness5/5

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

Two short sentences, zero waste, with the failure condition and the force override front-loaded in that order. Nothing could be removed without losing information.

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

Completeness4/5

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

The tool is simple (two parameters), an output schema exists so return values need no explanation, and the description covers the main non-obvious risk: reference failures and cascading deletion. Only the meaning of the required `tag` parameter and whether reference removal is recoverable are left unexplained.

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?

Schema description coverage is 0%, so the description carries the burden for both parameters. It explains `force` well (cascade removal of references, default false implied by the failure case) but says nothing about `tag` — whether it is a device identifier, name, or handle. Partial compensation only.

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?

The description opens with a specific verb+resource ('Remove a device'), which distinguishes it immediately from device_add, device_update and device_list. It does not explicitly name a sibling or clarify its scope relative to other remove-style tools (plc_io_remove, sheet_remove), so it stops short of 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 Guidelines4/5

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

It gives a concrete precondition ('Fails if it is referenced') and the conditional escape hatch ('unless force=true'), which is exactly the decision an agent needs before calling. It does not state when to prefer an alternative (e.g. unlinking references first or using device_update), so it is clear context without full alternative routing.

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