write_sdo

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

With no annotations, the description carries the full burden, yet says nothing beyond the mutation itself: no statement about persistence after power cycle, SDO abort/error behavior, timeouts, required device state, or whether value size is dictated by the object dictionary entry. For a write tool on hardware this is a meaningful gap.

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 zero filler — the verb and resource lead. It carries no wasted text, though its brevity leaves the behavioral gaps noted elsewhere.

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?

No output schema and no annotations means the description must cover the full picture for a hardware-mutating call, but it omits device-state preconditions, error/abort semantics, and persistency. The rich schema only covers parameter shape, not behavior.

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 index, subIndex (default 0), value and slaveIndex are already documented in the schema with formats. The description only restates Index and SubIndex, adding no meaning beyond the schema; baseline 3 applies.

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 (write) and resource (CoE SDO object) addressed by Index/SubIndex, which inherently separates it from read_sdo and the PDO siblings. It stops short of naming an alternative explicitly, but the object-dictionary framing is unambiguous.

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?

There is no guidance on when to use SDO versus the sibling write_pdo, no prerequisites (e.g. whether the slave must be in a particular EtherCAT state), and no mention of what happens on failure. The agent must infer usage purely from the terminology.

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