Query the EtherCAT State Machine state (INIT, PREOP, BOOT, SAFEOP, OP) for the bus or a specific slave to verify operational status and diagnose state issues.
Query the EtherCAT State Machine (ESM) state (INIT, PREOP, BOOT, SAFEOP, OP) for the bus or a specific slave.
| Name | Required | Description | Default |
|---|---|---|---|
| slaveIndex | No | Optional slave index. If omitted, queries the master/bus state. |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full behavioral burden. 'Query' correctly signals a safe read, and listing the possible state values compensates for the missing output schema, but nothing is said about permissions, behavior on an out-of-range slaveIndex, or whether the call fails when the bus is down.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the enumerated state list earns its place because no output schema exists to convey return values.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-optional-parameter query tool, the description plus schema cover what an agent needs to invoke it, and the state enumeration substitutes well for the absent output schema. Only error/failure conditions are left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's 'for the bus or a specific slave' merely paraphrases what the schema's slaveIndex description already states, adding no new syntax or constraint detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Query') and resource ('EtherCAT State Machine state') and enumerates the five possible states, which pins down exactly what is returned. It implicitly contrasts with the mutating sibling set_esm_state through 'Query', but never names it explicitly, so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer this is the read-side counterpart to set_esm_state, but the description never says when to reach for this versus get_diagnostics, get_slave_info, or scan_slaves. No exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.