Skip to main content
Glama
fieldpuppet

fieldpuppet

Official

Write raw Modbus values

write_registers
Idempotent

Writes raw values into a Modbus table starting at an address, including read-only tables to simulate sensor inputs and test SCADA systems without hardware.

Instructions

Write raw values into one Modbus table of a device, starting at an address: 0-65535 for holding and input registers, 0 or 1 for coils and discrete inputs. Unlike a Modbus client this can also write the read-only tables (discrete, input), which is how you fake sensor inputs at an address no point covers. Use set_point when the address belongs to a named point and you want scaling applied; a signal running on a point at that address will overwrite the value on its next update. Returns how many values were written.

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>",
      "table": "<table>",
      "address": "<address>",
      "values": "<values>"
    },
    "name": "write_registers"
  }
}

Input Schema

NameRequiredDescriptionDefault
tableYesModbus table: coil and discrete hold bits, holding and input hold 16-bit registers.
valuesYesValues for consecutive addresses, first value at 'address'.
addressYesZero-based address of the first value.
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. Changed4 schema fields changedv0.1.2
    • addedInput schema / properties / address / description
      Added value: +"Zero-based address of the first value."
    • 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."
    • addedInput schema / properties / table / description
      Added value: +"Modbus table: coil and discrete hold bits, holding and input hold 16-bit registers."
    • addedInput schema / properties / values / description
      Added value: +"Values for consecutive addresses, first value at 'address'."
  2. First observedv0.1.1

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations: it discloses that this tool can write the normally read-only discrete and input tables, and warns that a signal running on a point at that address will overwrite the value on its next update. It also states the return value (count of values written), none of which appears in the structured data.

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-loads the action and address rules, then the capability, then the alternative, then the return value – a sensible order with no filler sentences. The clause describing address ranges for coils is compact to the point of being hard to parse, which is the only cost.

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?

No output schema exists, yet the description names the return value; the overwrite hazard and read-only-table capability cover the main behavioral risks. With annotations and a fully documented schema already present, nothing an agent needs in order to call this correctly is missing.

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 per-table address semantics ('0-65535 for holding and input registers, 0 or 1 for coils and discrete inputs') that the schema does not. That address/table relationship is phrased loosely enough to be slightly ambiguous, so it stops short of 5.

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?

States a concrete verb and resource ('Write raw values into one Modbus table of a device, starting at an address') and immediately scopes it against siblings by naming set_point as the scaled/named-point path. An agent can distinguish it from set_point and read_registers 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?

Gives an explicit when-to-use case ('fake sensor inputs at an address no point covers') and an explicit when-to-use-something-else rule ('Use set_point when the address belongs to a named point and you want scaling applied'). It also warns about the consequence of choosing this tool on a point-backed address.

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