Skip to main content
Glama
fieldpuppet

fieldpuppet

Official

Create a simulated device

create_device

Start a simulated Modbus TCP device with configurable points, unit ID and port so real client software can connect for SCADA and gateway testing.

Instructions

Start one simulated Modbus TCP device that real client software can connect to. Use clone_device instead when you need many copies of a device that already exists, and load_project to bring back a saved set. Without a port the device gets the next free port; give a port already used by this simulator together with a different unit_id to put several devices behind one port. Fails if the id is taken, the port is used by another program, or the device limit is reached. Returns the device id plus the host, port and unit id to connect to.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "create_device"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoId for the new device: letters, digits, '-' and '_'. Omit to get <template>-N automatically.
nameNoDisplay name shown in list_devices and on the dashboard. Optional.
portNoTCP port to listen on. Omit for the next free port.
pointsNoExtra points, or replacements for template points with the same name.
strictNotrue: answer 'illegal data address' for addresses no point covers. Default false: unmapped addresses read 0.
unit_idNoModbus unit id the device answers to. Default 1.
scenarioNoTimeline of steps for one device.
templateNoBuilt-in template name (see list_templates). Omit for an empty device and supply points yourself.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed19 schema fields changedv0.1.2
    • changedInput schema / properties / id / description
      Previous value: -"Optional id: letters, digits, '-' and '_'."New value: +"Id for the new device: letters, digits, '-' and '_'. Omit to get <template>-N automatically."
    • changedInput schema / properties / name / description
      Previous value: -"Optional display name."New value: +"Display name shown in list_devices and on the dashboard. Optional."
    • addedInput schema / properties / points / items / description
      Added value: +"Definition of one point: a named value stored at a Modbus address."
    • changedInput schema / properties / points / items / properties / address / description
      Previous value: -"Zero-based protocol address."New value: +"Zero-based protocol address (holding register 40001 is address 0)."
    • addedInput schema / properties / points / items / properties / description / description
      Added value: +"Free text describing the point. Informational only."
    • addedInput schema / properties / points / items / properties / name / description
      Added value: +"Point name, unique within the device. Used by set_point, set_signal and read_points."
    • addedInput schema / properties / points / items / properties / table / description
      Added value: +"Modbus table: coil and discrete hold bits, holding and input hold 16-bit registers."
    • addedInput schema / properties / points / items / properties / unit / description
      Added value: +"Engineering unit shown next to the value, for example kW or bar. Informational only."
    • changedInput schema / properties / port / description
      Previous value: -"Optional TCP port. Omit for the next free port."New value: +"TCP port to listen on. Omit for the next free port."
    • addedInput schema / properties / scenario / properties / name / description
      Added value: +"Label shown in list_devices and on the dashboard. Optional."
    • changedInput schema / properties / scenario / properties / repeat / description
      Previous value: -"Start over after the last step."New value: +"Start over after the last step. Default false."
    • addedInput schema / properties / scenario / properties / steps / description
      Added value: +"Steps in any order; each runs once when its time is reached."
    • addedInput schema / properties / scenario / properties / steps / items / properties / action / description
      Added value: +"What the step does. set_point needs point and value; set_signal needs point and signal; clear_signal needs point; fault needs fault; clear_fault needs nothing else."
    • addedInput schema / properties / scenario / properties / steps / items / properties / at_s / description
      Added value: +"Seconds after the scenario starts at which this step runs."
    • addedInput schema / properties / scenario / properties / steps / items / properties / point / description
      Added value: +"Point name, for set_point, set_signal and clear_signal."
    • addedInput schema / properties / scenario / properties / steps / items / properties / value / description
      Added value: +"Engineering value, for set_point."
    • changedInput schema / properties / strict / description
      Previous value: -"Answer 'illegal data address' for addresses no point covers. Default false (unmapped addresses read 0)."New value: +"true: answer 'illegal data address' for addresses no point covers. Default false: unmapped addresses read 0."
    • changedInput schema / properties / template / description
      Previous value: -"Built-in template name (see list_templates). Optional."New value: +"Built-in template name (see list_templates). Omit for an empty device and supply points yourself."
    • changedInput schema / properties / unit_id / description
      Previous value: -"Modbus unit id. Default 1."New value: +"Modbus unit id the device answers to. Default 1."
  2. First observedv0.1.1

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare a non-read-only, non-destructive, closed-world, non-idempotent mutation, so the safety profile is covered. The description adds real value beyond that: default port allocation, port sharing via unit_id, three failure conditions (id taken, port held by another program, device limit), and the returned connection tuple. It stops short of stating whether partial failures leave a device behind, which would round it out.

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?

Five tight sentences, each carrying distinct information: purpose first, alternatives second, port semantics third, failure modes fourth, return value last. No filler and no repetition of the title.

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 an 8-parameter tool with nested point and scenario objects and no output schema, the description supplies the missing pieces: return payload shape, failure conditions, and port-allocation behavior. The nested structures are thoroughly documented in the schema itself, so no description burden remains there.

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%, so the baseline is 3, but the description adds meaning the schema does not: that omitting port yields the next free port and that a port may be reused when combined with a distinct unit_id. These are cross-parameter semantics an agent would otherwise miss.

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 first sentence gives a specific verb and resource ('Start one simulated Modbus TCP device') and adds a distinguishing qualifier that real client software can connect to it. It explicitly separates this tool from clone_device and load_project, so an agent can route correctly without opening a 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 names two alternatives with the exact condition that selects each: clone_device for many copies of an existing device, load_project to restore a saved set. It also explains port selection behavior and how to intentionally share a port via a different unit_id, which is precisely the decision an agent faces here.

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