Skip to main content
Glama
Sign In
mcp-synology

mcp-synology

by cmeans
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

restore_from_recycle_bin

Destructive

Restore deleted files and folders from a Synology shared folder's recycle bin back to their original location or a chosen destination folder, with an option to overwrite existing items.

Instructions

Restore deleted files or folders from one shared folder's recycle bin. Check what's there first with list_recycle_bin: every path must be in that share's bin, or nothing is restored. Without dest_folder, each item goes back to its original folder, which is re-created if it's gone. An item already at the destination is skipped and stays in the bin, unless overwrite=true, which replaces the existing one. A long restore keeps running on the NAS and returns a handle for file_task.

Input Schema

NameRequiredDescriptionDefault
pathsYesItems to restore, as paths in the bin the way list_recycle_bin shows them (`Shows/Ep1.mkv`); full paths such as `/video/#recycle/Shows/Ep1.mkv` work too.
shareYesThe shared folder whose bin holds the items, as a name (`video`) or path (`/video`).
overwriteNoReplace an item already at the destination (default false: it's skipped and stays in the bin).
dest_folderNoAn existing folder to restore everything into, flat (default: each item's original folder).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.9.1
    • addedInput schema / properties / dest_folder / description
      Added value: +"An existing folder to restore everything into, flat (default: each item's original folder)."
    • addedInput schema / properties / overwrite / description
      Added value: +"Replace an item already at the destination (default false: it's skipped and stays in the bin)."
    • addedInput schema / properties / paths / description
      Added value: +"Items to restore, as paths in the bin the way list_recycle_bin shows them (`Shows/Ep1.mkv`); full paths such as `/video/#recycle/Shows/Ep1.mkv` work too."
    • addedInput schema / properties / share / description
      Added value: +"The shared folder whose bin holds the items, as a name (`video`) or path (`/video`)."
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "result": {
-      "title": "Result",
-      "type": "string"
-    }
-  },
-  "required": [
-    "result"
-  ],
-  "title": "tool_restore_from_recycle_binOutput",
-  "type": "object"
-}New value: +null
  2. Addedv0.7.1

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare non-read-only and destructive=true; the description goes well beyond them by disclosing atomic all-or-nothing semantics, folder re-creation, skip-vs-overwrite behavior, and that long restores continue server-side returning a handle for file_task. This is exactly the operational context an agent needs before a destructive call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and scope, then the precondition, then the parameter behaviors in a logical order. Dense but nearly every clause carries new information; a couple of clauses duplicate schema-documented defaults.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive 4-parameter mutation with no output schema, the description covers preconditions, partial-failure semantics, destination behavior, and the async continuation path (file_task). Nothing an agent needs to invoke it safely is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description still adds value with the 'flat' behavior of dest_folder and the re-creation of the original folder when dest_folder is omitted, plus how overwrite interacts with the skip rule. Some of the restatement of overwrite semantics overlaps the schema, keeping it off a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+scope: 'Restore deleted files or folders from one shared folder's recycle bin.' It immediately distinguishes itself from the obvious sibling list_recycle_bin by naming it as the read-only precursor.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells the agent to call list_recycle_bin first and states the hard precondition ('every path must be in that share's bin, or nothing is restored'), which is effectively a when-not-to-use condition. The alternative sibling is named with the condition that selects it.

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

Deploy Server

Other Tools