ipc_reboot

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is fully covered by structured data. The description's 'Destructive-class' merely repeats that annotation and adds only the minor context that the operation goes through the System Service. It does not explain what gets destroyed, whether confirm_token is required, what delay_s does, or any permissions/auth needs.

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 very short and front-loads the action and target in the first clause. The trailing 'Destructive-class.' is redundant with the destructiveHint annotation, so that fragment does not fully earn its place, but overall it is not bloated.

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 destructive 3-parameter tool, the description leaves major gaps: no parameter semantics for confirm_token or delay_s, no usage guidance, and no alternatives to consider. Annotations and the output schema cover safety and return values, but the description still fails to give the agent enough to invoke the tool correctly with confirmation and delay options.

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 0%, so the description should carry the full burden of explaining the three parameters, but it does not. The phrase '(or shut down)' faintly hints at shutdown_only, yet delay_s and confirm_token receive no explanation at all, leaving critical semantics undocumented. This is inadequate for a destructive operation with a likely confirmation parameter.

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 states a specific verb+resource: 'Reboot (or shut down) the target IPC via the System Service.' This is clear and distinguishes the operation from passive reads and TwinCAT runtime restarts by specifying the IPC target and System Service channel. However, it does not explicitly name or contrast with sibling tools like xae_restart_twincat or tc_set_mode, so the sibling differentiation is only implicit.

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?

The description offers no when-to-use guidance, no prerequisites, and no alternatives. 'Destructive-class' signals caution but does not help the agent decide between this and other restart or shutdown tools. Usage is only implied by the tool name and purpose.

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