Manage Backups

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

The description discloses several behavioral traits beyond annotations: restore is undoable because current content rotates into prev, the payload is validated before the atomic replace, and purge defaults to dry_run and only deletes when dry_run=false. This materially exceeds what destructiveHint=true conveys.

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 packs a large amount of behavior into a compact semicolon-separated block with no filler. The opening noun phrase is slightly awkward and the density could be improved with bullets, but every clause earns its place.

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?

Given six parameters, a destructive risk profile, and no schema-level descriptions, the tool description covers the backup location, slot meanings, each action, restore safety, and deletion safeguards. Return values are not explained, but the presence of an output schema makes that unnecessary.

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%, but the description compensates by defining all six parameters: action values, source choices, scope values, file_path vs directory, and dry_run semantics. It maps parameter names to concrete examples, adding meaning not present in the input schema.

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 defines a backup-management tool by enumerating three actions—list, restore, and purge—against the .ks4p-backups/ slots, so an agent can tell what it does. It is less explicit than a clean 'manages automatic backups' statement and does not differentiate from the create_snapshot sibling, so it stops short of a 5.

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 actionable guidance per action: list for inspecting slots or orphaned folders, restore for overwriting from a source, and purge with dry_run safety. It does not explicitly contrast with sibling tools like create_snapshot, but the action-level conditions are clear.

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