plc_preview_iec_xml_import

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, and the description goes well beyond them: it discloses that array aliases are expanded inline rather than registered as named native DataTypes, that namespaces are flattened into the target table's flat scope with references rewritten, that duplicate names after flattening are rejected, and that no staging or Sysmac action occurs. It also spells out precise structural preconditions for rungs (linear or one two-path split/join, NO/NC contacts, single standard final coil, unique explicit evaluationOrder). Nothing here contradicts the read-only annotations.

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?

Every sentence carries substantive information, but it is delivered as a single dense block with comma splices and no structural grouping of purpose, supported constructs, blocked constructs, and parameter notes. The supported/blocked lists would be far more scannable as separate labeled sentences; as written, a reader must parse the whole block to find the one parameter-specific instruction.

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 high-complexity import-preview tool, the description covers the critical behavioral surface: supported subset, hard-blocked constructs, namespace flattening, duplicate rejection, and the guarantee of no external side effects. Return values are covered by the existing output schema, so their absence from the description is acceptable; the remaining gap is the unexplained required template_pou_ids map.

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 only 17% across 6 parameters, so the description needs to compensate and it only partly does. It adds real meaning for data_type_table_id (when to supply it) and clarifies transaction semantics, but template_pou_ids (a required nested object map) and schema_path are never explained, and xml_path/expected_revision get only indirect hints.

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?

The description opens with a specific verb+resource combination ('Preview PLCopen ST POUs...') and enumerates exactly what subset of IEC XML is understood (POUs, globals, structures, unions, DINT enums, 1-D array aliases, up to 1000 LD rungs). It also draws a clear boundary against the staging sibling by stating 'All edits stay in the local transaction; no staging or Sysmac action occurs.' An agent can distinguish this from plc_stage_iec_xml_import without opening either schema.

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?

It gives concrete selection guidance for one parameter ('pass data_type_table_id when the project has multiple tables') and enumerates the constructs that will be rejected, which effectively tells the caller when this tool will fail. What it does not do is explicitly name the alternative tool (plc_stage_iec_xml_import) or state 'use this first, then stage' as an ordered recommendation, leaving that inference to the agent.

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