Restore SwOS Backup

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: the whole configuration is replaced, the switch reboots and is unreachable for a while, and its address may change to the backup's. It also discloses mitigation (current config saved first by default) and the non-destructive default of dryRun=true.

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?

Four tight sentences, front-loaded with the action, then the operational consequences, then the safe defaults. No redundancy and every clause conveys decision-relevant information.

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, rebooting restore with no output schema, the description covers the blast radius, downtime, address change, and default safeguards. The confirmation/approval mechanics are fully specified in the schema's confirmationToken parameter, so nothing an agent needs is missing.

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 100%, so the schema already documents file, force, dryRun, routerId, saveCurrentFirst, and the confirmationToken flow. The description reinforces that dryRun defaults to true and that the current config is saved first, but adds no syntax or meaning beyond the schema, so baseline 3 is appropriate.

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+resource (restore a backup.swb onto the switch) and anchors it to a familiar reference point ('as the web UI's Restore Backup does'). This is clearly distinguishable from save_swos_backup and apply_swos_config without opening any 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?

Usage is implied by the scenario (restoring a stored backup), and it flags the destructive/reboot nature and the dryRun default, which is helpful context for deciding to call it. However, it never explicitly names the alternatives (apply_swos_config, upgrade_swos_firmware, save_swos_backup) or states when-not to use it, leaving routing to the agent's inference.

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