Skip to main content
Glama
ymxc152

plctap

by ymxc152
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Probe Device

probe_device
Read-onlyIdempotent

Troubleshoot PLC connection issues by probing reachability and communication, then classify failures into network, timeout, protocol, or unit/register errors to pinpoint the faulty layer.

Instructions

测试能否连上 PLC 并通信, 失败时给出层级归因。

reachable = 传输层可达 (TCP 已建立; 设备回异常响应也算在线)。 failure_class 取:

  • connection_refused: 端口没人监听/网络不可达 (查网络与端口)

  • timeout: 连接超时 (查网络路由/防火墙)

  • connected_but_no_reply: TCP 通了但设备不回话 (查协议配置)

  • exception_response: 设备回异常码 (查 unit/寄存器配置, 带 exception_code) 典型用法: 设备"读不到数据"时先调本工具分层定位, 再决定下一步。

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
hostYes
portYes
unitNo
protocolYes

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
identityNo
reachableYes
layer_hintNoapplication
failure_classNo
exception_codeNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.6.1
    • changedOutput schema / description
      Previous value: -"probe_device 输出: 连通性探测 + 四类失败归因 (PLAN.md 第 3 节)。\n\nreachable 语义 = 传输层可达 (TCP 已建立)。设备回异常响应\n(exception_response) 说明设备在线且协议栈正常, 此时 reachable=True,\nfailure_class/exception_code 给出应用层异常 —— 分层归因的锚点。\nreachable=True 且 failure_class=None 表示可正常交换数据。"New value: +"probe_device 输出: 连通性探测 + 四类失败归因。\n\nreachable 语义 = 传输层可达 (TCP 已建立)。设备回异常响应\n(exception_response) 说明设备在线且协议栈正常, 此时 reachable=True,\nfailure_class/exception_code 给出应用层异常 —— 分层归因的锚点。\nreachable=True 且 failure_class=None 表示可正常交换数据。"
    • addedOutput schema / properties / identity
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}
  2. First observedv0.4.0

TDQS

A4.1/5.0
Behavior5/5

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

With readOnlyHint=true and idempotentHint=true already covering safety, the description adds valuable behavioral semantics: reachable is defined as TCP established and includes exception responses, and each failure_class value is tied to a likely cause. This goes well beyond the annotations and gives the agent a mental model of expected outcomes.

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?

The description is front-loaded with the core purpose, then organized as a compact taxonomy of failure_class values, and ends with a typical-use directive. Each line earns its place, and the structured list makes the behavior easy to scan.

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?

Given the output schema exists and annotations cover side effects, the description is nearly complete for invoking the tool. It still leaves protocol/host/port/unit semantics to inference and doesn't mention the relationship to detect_device, so slightly more context would make it fully self-sufficient.

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 must compensate. It implicitly explains port (via connection_refused), protocol (via connected_but_no_reply), and unit (via exception_response), but it never formally defines the parameters or their allowed values/relationships. This is adequate for a PLC-expert agent but leaves gaps for less obvious parameters like protocol format.

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 states a specific purpose: test whether a PLC connection and communication are possible, with failure_class attribution on failure. It is clear about the resource and behavior, but it does not explicitly contrast with the similar-sounding sibling detect_device, so sibling differentiation is only implicit.

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?

The description gives a clear trigger: when the device 'cannot read data', call this tool first for layer-by-layer diagnosis. It does not spell out when not to use it or name alternative tools such as detect_device or diagnose, so it falls short of the strongest guidance.

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

Deploy Server

Other Tools