kodi_restore_file

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds real value beyond that: a required precondition (Kodi stopped), a validation behavior (stale checksums rejected), and a mitigating side effect (undo snapshot created). It stops short of noting auth requirements or irreversibility of the undo snapshot.

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?

One dense sentence, front-loaded with the operation, then precondition, validation, and side effect in order of importance. No wasted words.

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 mutation with an output schema present, the description covers precondition, validation, and rollback safety. The only gap is that backup_id's expected form is never clarified.

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 0%, so the description must compensate. 'Rejects stale checksums' does explain the role of expected_current_sha256 as a concurrency guard, but backup_id is left undefined (id format, where it comes from), so compensation is only partial.

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 (restore) and resource (one snapshot), and its scope ('one') cleanly separates it from kodi_backups and kodi_backup_file. An agent can identify the operation without opening the 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?

Gives a clear precondition ('while Kodi is stopped') that tells the agent when the call is valid, but names no alternatives (e.g., when to back up instead of restore) or exclusions beyond the stale-checksum rejection.

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