Skip to main content
Glama
Sign In
mcp-synology

mcp-synology

by cmeans
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

list_downloads

Read-only

List Download Station tasks with status, progress, speeds, ETA, and completion time. Filter or sort the whole queue to find active, paused, failed, or recently finished downloads.

Instructions

List download tasks in the Download Station queue. Returns a table with id, title, type (bt/http/ftp/nzb), status, size, progress%, download and upload speed, ETA, and completion time. Paged (25 by default); the footer gives the true total and the next offset. A status filter or sort covers the whole queue, not just one page: sort_by=completed with limit=1 gives the most recently finished task. Accounts that are not Download Station managers see only their own tasks (the output says so), so an empty list does not mean the NAS is idle.

Input Schema

NameRequiredDescriptionDefault
limitNoMost tasks to return, 1 or more.
offsetNoTasks to skip, 0 or more; the footer gives the next offset.
sort_byNo`queue` (default: queue order, oldest first), `created` or `completed` (both newest first; never-completed tasks last).queue
status_filterNo`all` (default), `downloading` (also waiting, finishing, hash checking, waiting for a file host, or extracting), `finished` (also seeding), `paused` or `error`.all

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.9.1
    • addedInput schema / properties / limit / description
      Added value: +"Most tasks to return, 1 or more."
    • addedInput schema / properties / offset / description
      Added value: +"Tasks to skip, 0 or more; the footer gives the next offset."
    • addedInput schema / properties / sort_by / description
      Added value: +"`queue` (default: queue order, oldest first), `created` or `completed` (both newest first; never-completed tasks last)."
    • addedInput schema / properties / status_filter / description
      Added value: +"`all` (default), `downloading` (also waiting, finishing, hash checking, waiting for a file host, or extracting), `finished` (also seeding), `paused` or `error`."
    • changedOutput schema / (root)
      Previous value: -{
-  "properties": {
-    "result": {
-      "title": "Result",
-      "type": "string"
-    }
-  },
-  "required": [
-    "result"
-  ],
-  "title": "tool_list_downloadsOutput",
-  "type": "object"
-}New value: +null
  2. Addedv0.7.1

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already establish readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that: paged output with a footer total, filter/sort covering the whole queue, and permission-scoped visibility for non-managers. The caveat that an empty list may reflect permissions rather than NAS idleness is especially useful.

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

Conciseness5/5

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

The description is front-loaded with the core purpose, then adds return shape, pagination, cross-page filtering semantics, and the permission caveat in a compact set of sentences. Every sentence contributes specific operational value.

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?

There is no output schema, but the description explains the return columns, footer behavior, and permission-scoped results. Combined with the read-only annotations and fully documented parameters, an agent has enough information to call this correctly.

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 description coverage is 100%, so the baseline is 3. The description adds cross-parameter meaning beyond the schema, notably that sort/filter operate across the full queue and that sort_by=completed with limit=1 returns the most recently finished task.

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?

The description states a specific verb and resource: list download tasks in the Download Station queue. It also immediately frames the result as a tabular summary, which distinguishes it from sibling tools like get_download_info and get_download_stats that focus on detail or aggregates.

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

Usage Guidelines4/5

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

The description gives clear usage context for pagination, status filtering, and sorting, including a concrete example of using sort_by=completed with limit=1 to find the latest finished task. It does not explicitly name alternatives such as get_download_info, so it stops short of full when-to-use routing.

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