plc_unassign_program

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

Annotations already declare destructive=true, idempotent=false and readOnly=false, so the safety profile is covered; the description goes beyond them by disclosing staging semantics, the refusal on inconsistent task models, archiving of the now-unreferenced association model file, that the Program and its source are unchanged, and that the result is unverified until a Sysmac rebuild. Only the permission/precondition story around transaction_id is left implicit.

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?

Three tightly packed sentences with the action front-loaded and each sentence carrying distinct information (action, refusal/archival behavior, invariants). Slightly dense phrasing but no filler.

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?

Output schema exists, so return values need not be explained, and the destructive/staging behavior is well covered. However, for a 4-parameter required-everything mutation tool at 25% schema coverage, the missing semantics for task_id, program_id and transaction_id leave an agent under-informed.

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 25% — just expected_revision is documented in the schema. The description alludes to 'selected task' and a staged change, but adds no meaning for task_id, program_id or transaction_id, leaving three of four parameters undescribed in both places.

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-and-resource pair: staging the removal of one Program assignment from a selected task. It is clearly distinct from plc_assign_program and from the commit tools via 'Stage', though it never names those siblings explicitly.

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 implied by 'Stage removal' plus the precondition that ambiguous or inconsistent task models are refused, which tells an agent when the call will fail. There is no explicit when-to-use versus plc_assign_program or plc_commit_changes guidance, and no mention that a transaction must be open first.

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