plc_assign_program

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

Beyond the annotations, it discloses that the operation atomically updates task XML and OEM links, rejects inconsistent identities, ambiguous instances, and cross-controller moves, and does not imply a PLC or Sysmac build. It also clarifies the default behavior for omitted position and startup arguments.

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?

The description is dense but front-loaded: the core action comes first, followed by parameter defaults, atomicity, rejection rules, and build implications. Every sentence adds relevant information without repetition.

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 mutation tool with a transaction/revision model, the description covers the assignment semantics, defaults, atomicity, and validation behavior. It leaves the transaction lifecycle and transaction_id usage unexplained, but the output schema and annotations reduce the remaining burden.

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 coverage is only 17%, so the description must carry parameter meaning. It usefully explains the ambiguous position and startup semantics, but it does not explain transaction_id or clarify how task_id and program_id are expected to identify their targets.

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 names a specific verb set (assign, move, reorder) and a precise resource (one Program in an existing task). It clearly distinguishes this from creation or removal operations by scoping the action to an existing task.

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 clear context for when this tool applies: assigning, moving, or reordering a program within an existing task, with cross-controller moves explicitly rejected. It does not explicitly name plc_unassign_program or other alternatives, so the guidance is strong but not fully complete on when-not to use it.

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