Skip to main content
Glama
fieldpuppet

fieldpuppet

Official

Remove one device

remove_device
Destructive

Stops a running simulated device and frees its port, discarding its points, values, traffic log, and scenario so Modbus clients can no longer connect.

Instructions

Stop one device and free its port. Its points, values, traffic log and running scenario are discarded and Modbus clients can no longer reach it. This cannot be undone unless the device was saved with save_project. Use remove_all_devices to clear everything. Fails if the id is unknown.

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": {
      "device_id": "<device_id>"
    },
    "name": "remove_device"
  }
}

Input Schema

NameRequiredDescriptionDefault
device_idYesId of a running device, as returned by create_device, clone_device or list_devices.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.2
    • changedInput schema / properties / device_id / description
      Previous value: -"Device id as returned by create_device or list_devices."New value: +"Id of a running device, as returned by create_device, clone_device or list_devices."
  2. First observedv0.1.1

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond that by enumerating exactly what is discarded (points, values, traffic log, running scenario) and who is affected (Modbus clients lose reachability). It also discloses irreversibility and the save_project escape hatch, which is the key operational caveat for a destructive 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/5

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

Four short sentences, each carrying distinct information: the action, the destruction set, the irreversibility caveat, and the sibling routing. The destructive consequence is front-loaded, so an agent skimming gets the most important fact first.

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

Completeness5/5

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

For a one-parameter destructive tool with no output schema, the definition covers action, side effects, affected consumers, reversibility, alternatives, and error behavior. There is no meaningful gap an agent would need to infer before calling it.

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

Parameters4/5

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

Schema coverage is 100% and the single parameter is already documented as an id from create_device, clone_device, or list_devices. The description adds one piece of semantic value beyond the schema: the unknown-id case fails rather than silently succeeding, which matters given idempotentHint=false.

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

Purpose5/5

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

The description opens with a specific verb and resource, "Stop one device and free its port," and immediately scopes it as single-device work in contrast to remove_all_devices. An agent can distinguish it from remove_all_devices and remove_point without opening any schema.

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

Usage Guidelines5/5

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

It explicitly names the alternative and the condition that selects it ("Use remove_all_devices to clear everything") and states the failure boundary ("Fails if the id is unknown"). The schema also routes the agent to the id sources, so there is no ambiguity about where the argument comes from.

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