This MCP server lets Claude monitor and manage a TrueNAS system in plain English. It is read‑only by default, with optional safe‑write and human‑confirmed destructive modes.
Monitoring (always available):
System & connection – Connection status, API mode (auto‑detected WebSocket or REST), authentication, version, hostname, uptime, CPU, RAM, load, updates, and reboot status.
Storage – ZFS pools (health, usage, scrub), datasets/zvols (space, quotas, compression), physical disks (model, serial, type, pool, temperature).
Snapshots & alerts – List snapshots (filter by dataset, paginate), active alerts (filter by severity).
Services & jobs – Status of SMB/NFS/SSH services, background jobs (scrubs, replications, etc.) with progress and errors.
Apps, sharing & VMs (25.04+) – Installed apps (state, version, updates), SMB/NFS/iSCSI shares, network config (IPs, routes, DNS), replication/cloud‑sync/snapshot/scrub task configs, VMs (state, resources).
Safe writes (enable with TRUENAS_ENABLE_WRITE=1):
Create/rename datasets, snapshots, SMB/NFS shares, users, groups, snapshot/scrub tasks. Update dataset properties. Manage services (start/stop/reload, boot setting). Control apps/VMs (start/stop/redeploy/upgrade). Run pool scrubs.
Destructive operations (requires both TRUENAS_ENABLE_WRITE=1 and TRUENAS_ENABLE_DESTRUCTIVE=1, plus explicit human confirmation):
Delete snapshots, datasets, shares, apps, VMs, users, groups. Rollback to snapshot, lock encrypted datasets. Pool device operations (detach/offline/remove vdev). Upgrade pool, reboot/shutdown, apply updates.
Safety & compatibility: Audit logging, fail‑closed on confirmations, secrets never exposed, plain HTTP refused unless explicitly allowed. Output in markdown (default) or JSON with schema validation. Auto‑detects TrueNAS API version.
Provides read-only monitoring and management of TrueNAS systems, including storage pools, datasets, snapshots, alerts, services, jobs, apps, shares, network, and backup tasks.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP-TrueNAS any alerts on the NAS?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that lets Claude monitor and manage a TrueNAS box in plain English: "any alerts on the NAS?", "how full is tank?", "list snapshots of appdata".
Read-only by default — the server observes and never mutates unless you opt
in. Safe, reversible writes are enabled with TRUENAS_ENABLE_WRITE=1;
destructive operations are separately gated and human-confirmed. See
Write support & safety.
┌───────────────── your Windows PC ─────────────────┐
│ │
│ Claude Code ◄── stdio (MCP JSON-RPC) ──► this │ ┌─────────┐
│ (you chat here) server ─┼──────► │ TrueNAS │
│ │ HTTPS/ │ (LAN) │
└─────────────────────────────────────────────────────┘ WSS └─────────┘This server runs on your PC, not on the NAS. Claude Code launches it
automatically as a background child process when a session starts (that's
what .mcp.json configures) and talks to it over stdin/stdout.
The server talks to TrueNAS over its network API, authenticating with an API key you generate in the TrueNAS UI.
stdout is sacred: it carries the MCP protocol. All logging goes to
stderr (console.error), never console.log.
TrueNAS changed APIs across versions, so the client auto-detects at runtime:
Your TrueNAS | API used | How |
25.04 "Fangtooth" and newer (incl. 26+) | WebSocket JSON-RPC 2.0 at |
|
SCALE ≤ 24.10, CORE 13.x | REST v2.0 at |
|
Version quirks handled for you: the snapshot API rename in 25.10
(zfs.snapshot.query → pool.snapshot.query), {"$date": …} timestamp
objects, and the login-method change coming in TrueNAS 27
(TRUENAS_USERNAME covers it).
Related MCP server: truenas-ws-mcp
File | Role |
Bootstrap: loads config from | |
Everything TrueNAS: API detection, WebSocket JSON-RPC with reconnect + login, REST fallback, and translation of raw network errors into actionable messages. | |
The MCP surface — every | |
Tells Claude Code how to launch this server (project-scoped registration). | |
Your secrets. Gitignored. |
All read-only (readOnlyHint: true), all paginate or filter where data can be
large. Each accepts response_format: markdown (default, compact summary) or
json (full structured data). Every tool also declares an outputSchema, so
the structured result is machine-validated by the MCP client.
System & storage
truenas_connection_status — diagnose config/reachability/auth; start here when something fails
truenas_get_system_info — version, hostname, uptime, CPU, RAM, load
truenas_check_updates — whether a base-OS update is available, plus reboot-required state
truenas_list_pools — pool health, capacity, usage %, fragmentation, scrub activity
truenas_get_pool — one pool's full topology (data/cache/log/spare vdevs, per-disk state & errors) + scrub status
truenas_list_datasets — space used/available, quotas, compression (filter by pool, paginated)
truenas_get_dataset — one dataset's full properties: encryption, quotas, recordsize, compression ratio, dedup, sync
truenas_encryption_summary — encrypted dataset key/lock status (no key material shown)
truenas_list_disks — model, serial, size, pool membership, optional temperatures
truenas_list_snapshots — snapshots with creation time and space (filter by dataset, paginated)
Health & activity
truenas_list_alerts — active alerts, filterable by severity
truenas_list_services — SMB/NFS/SSH/… state and boot setting
truenas_list_jobs — background jobs: scrubs, replications, failures
Apps, sharing, backups & VMs — require TrueNAS 25.04+ (WebSocket API)
truenas_list_apps — installed apps and whether an app/image update is available, plus Docker status
truenas_list_catalog_apps — browse the catalog of installable apps (filterable); source for create_app
truenas_get_app — one app's state, version, portals, host ports, container/volume counts (raw config omitted for safety)
truenas_list_vm_devices — a VM's disks, NICs, display, and passthrough devices
truenas_list_shares — SMB shares, NFS exports, and iSCSI targets in one call
truenas_iscsi_overview — full iSCSI config: targets, extents, LUN maps, portals, initiators, CHAP (secrets stripped)
truenas_nvme_overview — full NVMe-oF config: subsystems, namespaces, ports, hosts, and their links
truenas_list_network — IP addresses, default routes, DNS, and per-interface link state
truenas_list_replication_tasks — configured ZFS replication (backup) tasks and last-run state
truenas_list_cloudsync_tasks — cloud backup tasks (S3/Drive/B2/…); credentials never shown
truenas_list_rsync_tasks — rsync backup tasks (to another host/rsyncd) with direction, remote target, and last run
truenas_list_snapshot_tasks — periodic (automatic) snapshot policy and retention
truenas_list_scrub_tasks — scheduled pool scrub tasks
truenas_list_vms — virtual machines, run state, and resource allocation
System configuration & inventory (read)
truenas_system_config — general/advanced/security/system-dataset settings and current system state
truenas_boot_status — boot pool health and boot environments (rollback targets)
truenas_list_ntp_servers — configured time sources
truenas_list_init_scripts — custom init/shutdown scripts (command & script hooks)
truenas_list_cron_jobs — user cron jobs with schedule and enabled state
truenas_list_tunables — sysctl / kernel / rc tunables
truenas_get_network_config — global network config, static routes, and SSH bind settings (SSH keys stripped)
truenas_get_service_configs — SSH, SNMP, and UPS service configuration (community strings, v3 & UPS passwords stripped)
truenas_get_notification_config — email settings, alert services, and alert-class levels (mail password/OAuth stripped)
Identity, hardware & filesystem (read)
truenas_list_users — local/directory users: uid, shell, groups, sudo/lock/2FA, API-key count (password hashes never shown)
truenas_list_groups — groups: gid, members, sudo/SMB flags, builtin status, RBAC roles
truenas_list_certificates — TLS certificates with validity dates (bodies & keys never shown)
truenas_list_api_keys — programmatic API keys, linked user, expiry (key hash never shown)
truenas_list_sessions — who this server authenticates as, plus all active API/UI sessions
truenas_list_privileges — RBAC: which groups map to which admin roles
truenas_get_directory_services — Active Directory / LDAP / IPA join status (bind creds stripped)
truenas_get_hardware — IPMI/BMC presence, chassis status, and enclosure mapping
truenas_check_dependencies — what tasks/shares/processes depend on a dataset (pre-delete safety)
truenas_browse_path — read-only directory listing with stat and optional ACL
truenas_disk_temperature_alerts — disks running over their temperature threshold
Writes (opt-in — set TRUENAS_ENABLE_WRITE=1) — reversible, non-destructive; never marked read-only (so a client won't auto-run them); every call is audit-logged to stderr:
truenas_create_snapshot — take a ZFS snapshot of a dataset (optionally recursive)
truenas_update_dataset — change dataset properties (comment, compression, readonly, atime, sync, quota)
truenas_control_service — start / stop / restart / reload a service (smb, nfs, ssh, …)
truenas_set_service_boot — enable/disable a service starting on boot
truenas_manage_app — start / stop / redeploy / upgrade / rollback an installed app
truenas_create_app / truenas_update_app — install an app from the catalog; change an app's config values
truenas_manage_vm — start / stop / restart / suspend / resume a VM
truenas_create_vm / truenas_update_vm — create a VM shell; change its CPU/memory/boot config
truenas_run_scrub — start a manual pool scrub
truenas_download_update — download & stage the pending OS update without installing it (no boot-env change, no reboot)
truenas_run_cloudsync_task / truenas_run_replication_task / truenas_run_rsync_task — trigger an existing backup task now (by id)
truenas_clone_snapshot — clone a snapshot into a new dataset (non-destructive; great for file recovery)
truenas_create_rsync_task / truenas_update_rsync_task — define/adjust an rsync backup to another NAS (does not touch local SSH)
truenas_create_dataset / truenas_rename_dataset — create a dataset or zvol; rename a dataset
truenas_unlock_dataset — unlock an encrypted dataset (passphrase/key never logged)
truenas_change_dataset_key — rotate an encrypted dataset's passphrase/key (data preserved)
truenas_promote_dataset — promote a clone so it no longer depends on its origin snapshot
truenas_hold_snapshot / truenas_release_snapshot — protect a snapshot from deletion, then release it
truenas_create_smb_share / truenas_update_smb_share — SMB shares
truenas_create_nfs_share / truenas_update_nfs_share — NFS exports
iSCSI: truenas_create_iscsi_portal / _target / _extent / _targetextent / _auth / _initiator — build a full iSCSI LUN stack (CHAP secrets never logged)
NVMe-oF: truenas_create_nvme_subsystem / _namespace / _port / _port_subsys / _host — build a full NVMe-over-Fabrics target
truenas_create_user / truenas_update_user / truenas_set_user_password — local users (passwords never logged)
truenas_create_group / truenas_update_group — local groups
truenas_create_api_key / truenas_update_api_key — create/rename/reset/revoke API keys (key shown once, never logged)
truenas_create_certificate — import a cert (+ private key) or generate a CSR (private key never logged)
truenas_create_snapshot_task / truenas_update_snapshot_task — automatic snapshot schedules
truenas_create_scrub_task / truenas_update_scrub_task — scheduled scrubs
truenas_update_system_general / truenas_update_system_advanced — non-network system settings (timezone, MOTD, console, etc.)
truenas_update_email — outgoing SMTP for alerts (password never logged)
truenas_create_init_script / truenas_update_init_script — init/shutdown hooks
truenas_create_ntp_server / truenas_update_ntp_server — NTP time sources
truenas_create_cron_job / truenas_update_cron_job — scheduled commands
truenas_create_tunable / truenas_update_tunable — sysctl / udev / rc tunables
Destructive (opt-in — set BOTH TRUENAS_ENABLE_WRITE=1 and TRUENAS_ENABLE_DESTRUCTIVE=1) — irreversible; destructiveHint:true; each requires a human elicitation confirmation and refuses if the client can't be prompted:
truenas_delete_snapshot / truenas_delete_dataset — delete a snapshot / dataset (destroys data)
truenas_delete_smb_share / truenas_delete_nfs_share — remove a share (underlying data kept)
truenas_delete_rsync_task / truenas_delete_cloudsync_task / truenas_delete_replication_task — remove a backup task (already-synced data kept)
truenas_delete_iscsi — delete an iSCSI target/extent/targetextent/portal/initiator/auth by id (backing zvol/file kept)
truenas_delete_nvme — delete an NVMe-oF subsys/namespace/port/port_subsys/host/host_subsys by id (backing zvol/file kept)
truenas_delete_app / truenas_delete_vm — delete an app / VM (optionally its data too)
truenas_delete_user / truenas_delete_group — delete a user / group
truenas_delete_api_key / truenas_delete_certificate — delete an API key / certificate
truenas_rollback_snapshot — revert a dataset to a snapshot (discards newer data)
truenas_lock_dataset — lock an encrypted dataset
truenas_pool_detach_disk / truenas_pool_offline_disk / truenas_pool_remove_vdev — pool device operations
truenas_upgrade_pool — apply ZFS feature flags (irreversible)
truenas_delete_config — delete a non-network config item (init_script / ntp_server / cron_job / tunable) by id
truenas_reboot_system / truenas_shutdown_system — reboot / power off the NAS
truenas_apply_update — apply the pending OS update and reboot
The server is read-only until you opt in, in tiers:
Tier | Enable with | Gate |
Read (default) | always on | none |
Safe write (reversible) |
| not registered unless enabled; audit-logged; never marked read-only |
Destructive (delete / rollback / reboot) |
| the above plus a human elicitation confirmation, and fail-closed if the client can't prompt |
Status: the full read/write surface is implemented — 47 read, 63 safe-write, 25 destructive tools (135 total). Destructive tools appear only when BOTH flags are set, and each requires a human elicitation confirmation (fail-closed if the client can't be prompted).
Being honest about enforcement: MCP has no protocol-level way to force human
confirmation, so the guarantees that actually hold are the ones a client cannot
bypass — destructive tools are absent from the tool list unless the operator
sets the flag, and they refuse to run when a human can't be prompted.
Elicitation prompts and Claude Code ask/deny permission rules add
defense-in-depth but are bypassable (--dangerously-skip-permissions,
auto-accepting clients). The most dangerous operations — disk.wipe,
pool.create (formats disks), pool.export with destroy — are deliberately
not implemented; do those in the TrueNAS UI.
Testing writes safely: set TRUENAS_TEST_DATASET=tank/mcp-test to restrict
every write to that dataset and its children, so a mistake can't reach real
data — or point the server at a throwaway TrueNAS VM for write development.
In the TrueNAS web UI: user icon (top right) → My API Keys → Add.
Copy the whole <id>-<secret> string — it is shown exactly once.
An API key inherits the privileges of the user it's linked to. For a
belt-and-braces read-only setup, create a dedicated user whose group has only
the READONLY_ADMIN privilege (Credentials → Groups/Privileges) and link
the key to that user — then even a leaked key can't change anything.
API keys are password-equivalent and bypass 2FA. TrueNAS auto-revokes keys that ever travel over plain HTTP — always use
https://.
copy .env.example .envEdit .env: set TRUENAS_URL and TRUENAS_API_KEY; set
TRUENAS_SKIP_TLS_VERIFY=1 if the NAS uses its default self-signed
certificate.
npm installnpm run buildThis repo ships a project-scoped .mcp.json that launches the
server via a relative path (dist/index.js). Once you've built it, Claude
Code asks to approve the server the first time you open a session in this
folder, then launches it automatically thereafter.
To use it from any folder, register it user-wide with the absolute path to your clone:
claude mcp add --scope user --transport stdio truenas -- node /absolute/path/to/MCP-TrueNAS/dist/index.jsCheck it connected with claude mcp list (or /mcp inside a session).
Just ask Claude things like:
"How healthy are my pools?"
"Anything above WARNING in the NAS alerts?"
"Which disks are hottest right now?"
"Are any jobs failing? Show the errors."
MCP Inspector is a debugging client. Two flavors:
npm run inspectopens a web UI (browse tools, call them, see raw protocol traffic), or the scriptable CLI:
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/call --tool-name truenas_list_poolsEvery tool in src/tools.ts follows one pattern:
server.registerTool(
"truenas_list_pools", // snake_case, service-prefixed
{
title: "List Storage Pools",
description: "…written FOR the model: what it returns, when to use it…",
inputSchema: z.object({ // zod validates before your code runs
pool: z.string().optional().describe("shown to the model too"),
}),
annotations: { readOnlyHint: true, openWorldHint: false },
},
async ({ pool }) => {
try {
const data = await getClient().pools(); // client hides WS-vs-REST
return respond(structured, format, () => markdown);
} catch (error) {
return errorResult(error); // actionable, never a crash
}
}
);To add a write tool later (start a scrub, take a snapshot): add a client
method for the API call, register the tool with honest annotations
(readOnlyHint: false, destructiveHint as appropriate) — Claude Code will
then treat it with matching caution. Rebuild (npm run build) and restart
the session; Claude picks up the new tool automatically.
Symptom | Likely cause / fix |
Any tool errors | Ask Claude to run |
"TLS certificate verification failed" | Self-signed cert on the NAS → |
"Cannot reach …" | Wrong |
"TrueNAS rejected the API key" | Key mistyped/revoked — regenerate; copy the whole |
Key suddenly stopped working | Was it ever sent over |
Tools missing in Claude |
|
The API key lives only in .env (gitignored) or the MCP client's env
config — never in source, never in chat.
v1 tools are read-only by design; the key's user can enforce the same
server-side via READONLY_ADMIN.
Plain-HTTP URLs are refused unless TRUENAS_ALLOW_HTTP=1, because TrueNAS
revokes keys observed on unencrypted transport.
TLS verification is on unless you explicitly disable it for a self-signed cert.
Some TrueNAS read APIs return secrets (cloud-sync OAuth tokens, a VM's VNC
password). The tools that touch those — truenas_list_cloudsync_tasks and
truenas_list_vms — deliberately project only non-sensitive fields, so no
tokens, secrets, or passwords are ever surfaced to the model.
MIT © PainInTheNic
Check whether a TrueNAS base-OS (system) update is available, and whether the system is waiting on a reboot. Reports the current version and, if an update exists, the candidate version and release notes. Note: this covers the TrueNAS OS only — it does NOT check for app/catalog updates.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| train | Yes | |
| new_version | Yes | |
| reboot_reasons | Yes | |
| current_version | Yes | |
| reboot_required | Yes | |
| update_available | Yes | |
| release_notes_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context by specifying that the tool reports the current version, candidate version, release notes, and reboot waiting status. It also clarifies scope limitations (no app updates). No contradictions with annotations exist.
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 is three sentences, front-loading the primary action, followed by output details and a scope note. Every sentence contributes meaningful information with no redundancy or fluff.
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 the tool's simplicity (1 optional parameter, output schema exists, annotations present), the description is complete: it states what is checked (update availability, reboot pending), what is reported (versions, release notes), and what is excluded (app updates). This is sufficient for an agent to correctly select and invoke the tool.
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%. The single parameter 'response_format' is fully documented in the schema with enum values and descriptions. The tool description adds no additional parameter semantics, so the baseline of 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?
The description clearly states the tool's function: 'Check whether a TrueNAS base-OS (system) update is available, and whether the system is waiting on a reboot.' It specifies the resource (TrueNAS OS) and distinguishes itself from app/catalog updates, making it distinct from sibling tools like truenas_list_apps. It also enumerates the key outputs (current version, candidate version, release notes).
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?
The description provides an explicit exclusion: 'this covers the TrueNAS OS only — it does NOT check for app/catalog updates,' which constitutes a clear when-not-to-use. The context for when to use is implied by 'Check whether... update is available.' However, it does not name an alternative tool, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diagnose the connection to TrueNAS: shows the configured URL, whether an API key is present (never the key itself), which API generation was detected (WebSocket JSON-RPC vs legacy REST), and whether authentication succeeded. Call this first when any other truenas_ tool fails.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| hint | No | |
| uptime | No | |
| api_mode | No | |
| hostname | No | |
| reachable | No | |
| probe_error | No | |
| truenas_url | Yes | |
| api_versions | No | |
| authenticated | No | |
| api_key_present | Yes | |
| truenas_version | No | |
| tls_verification | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds critical behavioral details: it never reveals the API key itself, and it reports API generation detection and authentication success. This gives agents a fuller understanding of what the tool returns and its privacy safeguards. It does not contradict annotations.
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 is two sentences, front-loaded with the tool's purpose, followed by a concise list of returned information and an explicit usage directive. No filler or redundancy.
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 the tool's simplicity (zero required parameters), the presence of an output schema, and the description covering purpose, usage timing, and expected outputs, the description is fully sufficient for an agent to select and correctly invoke this tool.
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?
The input schema already fully describes the only parameter (response_format) with enum values and their meaning. The description doesn't add anything about the parameter, and with 100% schema coverage, the baseline of 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?
The description delivers a specific verb+resource combination: 'Diagnose the connection to TrueNAS' and enumerates exactly what is shown (configured URL, API key presence, API generation, authentication success). This clearly distinguishes it from sibling data-access tools like truenas_get_system_info or truenas_list_pools.
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 explicitly instructs to 'Call this first when any other truenas_ tool fails,' providing an unambiguous usage scenario and prioritizing it as a diagnostic entry point. This contrasts with siblings, which are for specific resource queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get system information from TrueNAS: product version, hostname, uptime, CPU model and core count, physical memory, load averages, boot time, and timezone.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| cores | Yes | |
| memory | Yes | |
| uptime | Yes | |
| loadavg | Yes | |
| version | Yes | |
| boottime | Yes | |
| hostname | Yes | |
| timezone | Yes | |
| cpu_model | Yes | |
| ecc_memory | Yes | |
| memory_bytes | Yes | |
| physical_cores | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds no additional behavioral traits beyond the fields returned, which is useful but not rich behavioral context. There is no contradiction with annotations.
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 is a single sentence that front-loads the action and resource, then lists the specific data fields. Every part is informative and there is no redundancy or unnecessary detail.
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 read-only system info tool with one optional parameter and an output schema, the description is sufficiently complete. It covers all key data points and relies on the schema for response_format details. It could mention error behavior, but that is beyond the expected scope for a simple getter.
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?
There is one parameter (response_format) with 100% schema coverage, including an enum and descriptions for 'markdown' and 'json'. The description does not mention the parameter or add any semantics beyond what the schema provides, so the baseline 3 applies.
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 uses a specific verb 'Get' and a clear resource 'system information from TrueNAS', and enumerates the exact data fields returned (product version, hostname, uptime, CPU, memory, load, boot time, timezone). This distinguishes it from sibling tools that target specific subsystems like pools or datasets.
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?
The description provides clear context by listing the system-wide metrics covered, implicitly indicating that this tool is for holistic system info rather than component-specific lists. It does not explicitly name alternatives or exclusion criteria, but the field list makes the intended usage obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List current TrueNAS alerts (warnings, errors, hardware problems, update notices). By default hides alerts the user already dismissed. Use min_level to only see serious ones.
| Name | Required | Description | Default |
|---|---|---|---|
| min_level | No | Only alerts at or above this severity (INFO < NOTICE < WARNING < ERROR < CRITICAL < ALERT < EMERGENCY) | |
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| include_dismissed | No | Also include alerts the user dismissed |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| alerts | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds valuable behavioral context about the default hiding of dismissed alerts and the 'current' nature of the listing, which goes beyond the structured annotations. No contradiction found.
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 consists of two efficient sentences: the first defines the tool's purpose with examples, the second covers default behavior and parameter usage. Every word contributes value.
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 simple read-only list tool with full parameter documentation, an output schema, and annotations declaring read-only safety, the description is complete. It covers the essential behavior and filtering guidance without unnecessary detail.
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?
The input schema has 100% coverage of all three parameters with detailed descriptions and defaults. The description's mention of min_level and dismissed alerts only reinforces schema information without adding new semantic meaning, 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?
The description clearly states the tool lists current TrueNAS alerts with specific examples (warnings, errors, hardware problems, update notices). This distinguishes it from sibling list tools that target other resources, making the purpose unambiguous.
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?
The description provides clear context for when to use the tool (when current alerts are needed) and even suggests using min_level to filter for serious alerts. It does not explicitly mention alternatives or exclusions, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List installed TrueNAS apps (the Docker-based Apps catalog, 24.10+) with their running state, current version, and — the key part — whether an app or catalog update is available (upgrade_available / image_updates_available). Also reports the Docker backend's status. This is the app-level counterpart to truenas_check_updates, which only covers the base OS.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| apps | Yes | |
| count | Yes | |
| docker_status | Yes | |
| upgrades_available | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safe read-only nature is known. The description adds valuable context: it specifies the version scope (24.10+), discloses that it also reports Docker backend status, and highlights the update availability fields. This goes beyond the annotations without contradicting them.
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 is two sentences, front-loaded with the core purpose, and every clause adds value. The 'key part' emphasis is a helpful structural cue, and there is no redundant or filler text.
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 the tool's moderate complexity (1 optional param, read-only, output schema present), the description covers all essential aspects: what is listed (apps, state, version, update status), the version requirement, and the distinction from the closest sibling. The output schema handles return structure, so no further return details are needed.
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?
The only parameter (response_format) is fully described in the input schema, covering 100% of schema description coverage. The description itself does not add parameter-specific details, but the schema already provides full context, meeting the baseline of 3.
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 uses the specific verb 'List' and clearly identifies the resource: installed TrueNAS apps. It distinguishes from the closely related sibling tool truenas_check_updates by explicitly stating it is the app-level counterpart, making the purpose unmistakable.
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?
The description directly tells the agent when to use this tool versus truenas_check_updates: this covers apps, while check_updates only covers the base OS. This explicit comparison provides clear usage guidance and an alternative, fulfilling the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List configured cloud sync tasks (backups to/from S3, Google Drive, Backblaze, etc.) with local path, direction, provider, schedule, and last-run state. Credentials, tokens, and secrets are deliberately never included.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| tasks | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds a valuable behavioral guarantee: 'Credentials, tokens, and secrets are deliberately never included.' This goes beyond annotations by assuring users about sensitive data handling. It does not cover all behaviors (e.g., pagination) but provides useful context.
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 is two sentences, front-loaded with the action and resource, and every clause adds value (field list, provider examples, credential exclusion). 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 simple list tool with one parameter, an output schema, and read-only annotations, the description sufficiently covers what the tool does and important caveats (no secrets). It doesn't need to explain return values because an output schema exists.
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% with the response_format parameter fully described in the schema, including enum values and default. The description itself adds no extra parameter semantics, so the baseline of 3 applies.
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 uses a specific verb ('List') and resource ('configured cloud sync tasks'), and elaborates with concrete field details (local path, direction, provider, schedule, last-run state) and provider examples (S3, Google Drive, Backblaze). This clearly distinguishes it from sibling list tools.
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?
The description implies when to use it (whenever cloud sync task info is needed) but does not explicitly mention alternatives or exclusions. It lacks guidance on when not to use it or how it differs from other list tools beyond the resource type.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List ZFS datasets (filesystems and zvols) with space used/available, snapshot usage, quota, compression, and mountpoint. Filter by pool and paginate for large systems.
| Name | Required | Description | Default |
|---|---|---|---|
| pool | No | Only list datasets in this pool (e.g. 'tank') | |
| limit | No | Maximum datasets to return | |
| offset | No | Datasets to skip, for pagination | |
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| offset | Yes | |
| datasets | Yes | |
| has_more | Yes | |
| next_offset | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes that this is a safe read operation. The description adds context by listing the specific data fields returned and noting pagination. No contradictions with annotations, and no need to disclose destructive behavior.
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?
Two sentences are front-loaded with the action and resource, followed by compact details on output fields and usage. No waste; every clause adds meaningful 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 simple read-only list tool, the description is complete given the presence of an output schema and annotation. It covers both dataset types, key output attributes, and usage hints. No critical gaps.
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 100%, with each parameter (pool, limit, offset, response_format) already documented in the input schema. The description merely echoes 'filter by pool' and 'paginate' without adding new parameter semantics beyond what the schema provides.
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 uses the specific verb 'List' with a clear resource 'ZFS datasets (filesystems and zvols)' and enumerates the returned attributes (space, snapshot usage, quota, compression, mountpoint). This makes it distinct from siblings like list_pools and list_snapshots.
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?
The description provides practical context: 'Filter by pool and paginate for large systems.' This indicates when to use the tool but does not explicitly mention alternatives or when-not-to-use it relative to other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List physical disks with model, serial number, size, type (HDD/SSD), which pool each belongs to, and optionally the current temperature in °C (readings are cached ~5 minutes by TrueNAS).
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| include_temperatures | No | Also fetch current disk temperatures |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| disks | Yes | |
| temperature_error | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds valuable context about temperature readings being cached ~5 minutes by TrueNAS, which is a behavioral trait beyond the annotation. This helps the agent understand potential staleness of temperature data.
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 is a single, well-structured sentence that front-loads the action and resource, then details the returned fields and optional temperature. No wasted words; every clause adds value.
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 the tool's low complexity, the presence of an output schema, and the readOnlyHint annotation, the description is sufficient for the agent to select and invoke the tool correctly. It covers output contents, optional parameters, and the caching caveat, making it complete for this context.
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?
The input schema fully describes both parameters (response_format and include_temperatures) with descriptions and defaults, achieving 100% schema coverage. The description does not add any additional parameter semantics beyond what the schema already provides, so baseline 3 applies.
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 uses the specific verb 'List' with the resource 'physical disks' and enumerates the exact attributes returned (model, serial number, size, type, pool, optional temperature). This clearly distinguishes it from sibling tools like truenas_list_pools, which list pools rather than disks.
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?
The description implies usage for retrieving physical disk inventory, including optional temperature readings. It does not explicitly state when to use this over alternatives or exclude any scenarios, but the context is clear from the tool name and description. Score 4 for clear implied usage without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List TrueNAS background jobs (scrubs, replications, updates, ...), most recent first, with state (WAITING/RUNNING/SUCCESS/FAILED/ABORTED), progress percent, and errors. Use state=RUNNING to see what the NAS is doing right now, state=FAILED to find recent failures.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum jobs to return | |
| state | No | Only jobs in this state | |
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| jobs | Yes | |
| count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows it is a safe read. The description adds meaningful behavioral context: results are 'most recent first' and include state, progress percent, and errors. This goes beyond the basic read-only hint, though it doesn't discuss pagination or rate limits.
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 is two sentences, concise and front-loaded with the verb and resource. The first sentence covers what it lists and the output details; the second sentence provides actionable usage examples. No filler 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 simple read-only listing tool with three optional parameters, an output schema, and a readOnlyHint annotation, the description fully covers the purpose, output, and practical usage. There is no missing critical information; the output schema handles return formats, and the annotations cover safety.
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% with descriptive parameter comments. The description adds extra guidance for the 'state' parameter by giving concrete use cases (RUNNING for current activity, FAILED for failures). While limit and response_format are not further explained, the baseline 3 is elevated to 4 because of this added practical parameter usage.
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 uses a specific verb ('List') with a specific resource ('TrueNAS background jobs') and provides concrete examples (scrubs, replications, updates). It clearly distinguishes itself from sibling tools like list_replication_tasks or list_scrub_tasks by covering all background jobs, not just one type.
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?
The description gives explicit practical guidance: 'Use state=RUNNING to see what the NAS is doing right now, state=FAILED to find recent failures.' This clearly indicates when to use the tool with which parameter. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of full exclusions/alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compact network health view: a summary of IP addresses per interface, default routes, and DNS nameservers, plus per-interface type, link state, MAC, addresses, and MTU. The first stop for 'is the NAS's networking okay?' or diagnosing a down NIC.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| interfaces | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the tool is known to be safe. The description adds behavioral context by specifying the exact data returned (e.g., per-interface type, link state, MAC, addresses, MTU) and calls it a 'compact health view.' It does not reveal potential edge cases or rate limits, but with strong annotations and output schema, this is sufficient for a read-only listing tool.
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 is two sentences, front-loaded with the core concept 'Compact network health view,' and includes a concise enumeration of data fields. The final sentence provides actionable use cases without any filler. Every phrase 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 the tool's simplicity, one optional parameter, and an existing output schema, the description is complete enough. It covers the tool's scope, return content, and intended use case. The output schema handles detailed return structure, so the description doesn't need to elaborate further.
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?
The input schema covers 100% of the single parameter (response_format) with a clear enum, default, and explicit description. The tool description itself does not mention the parameter, but per the rubric, baseline is 3 when schema coverage is high. No additional semantic value is needed from the description.
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 clearly states what the tool does: it provides a 'compact network health view' with a specific list of data (IP addresses per interface, default routes, DNS nameservers, per-interface type, link state, MAC, addresses, MTU). It also distinguishes itself from siblings by positioning as 'the first stop' for network health queries and NIC diagnostics, making its purpose unambiguous.
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?
The description gives clear context on when to use this tool: 'The first stop for 'is the NAS's networking okay?' or diagnosing a down NIC.' It does not explicitly name alternatives or exclusion criteria, but it establishes a clear primary use case. Sibling tools like truenas_connection_status exist, but no direct comparison is provided, so this is a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all ZFS storage pools with health status (ONLINE/DEGRADED/FAULTED), capacity (size, allocated, free, usage %), fragmentation, and any running scrub/resilver. The first stop for 'how are my pools?' or 'how full is my NAS?'.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| pools | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds contextual detail about the output content (health, capacity, fragmentation, running scrub/resilver). This goes beyond the structured annotations by describing what the tool reveals about system state, without contradicting the read-only nature.
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?
Two sentences, front-loaded with the action and resource, followed by data details and usage pointer. Every sentence adds value without redundancy.
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 read-only list tool with one optional parameter, full schema coverage, and an output schema, the description provides ample context: what data is included, the usage scenario, and the fact it's a first-stop overview. No significant gaps remain.
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?
The single parameter (response_format) is fully described in the schema with enum and default, giving 100% schema coverage. The description does not add extra parameter semantics, but with complete schema documentation the baseline of 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?
The description clearly states a specific verb ('List') and resource ('all ZFS storage pools'), and enumerates the exact data returned (health status, capacity, fragmentation, scrub/resilver). This distinguishes it from sibling tools like list_datasets or list_disks.
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 provides clear usage context with 'The first stop for how are my pools? or how full is my NAS?', indicating when to reach for this tool. It does not explicitly exclude alternatives or name sibling tools, but the purpose is specific enough that usage is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List configured ZFS replication tasks (backup jobs that send snapshots to another dataset or a remote box) with direction, transport, whether they're enabled, and last-run state. Unlike truenas_list_jobs, this shows the task CONFIGURATION even when nothing is running.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| tasks | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and the description reinforces this with 'List'. It adds valuable context beyond annotations: it reveals that configurations are shown even when nothing is running, and that enabled status and last-run state are included. No contradiction with annotations.
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?
Two sentences: the first is front-loaded with the core action and scope, the second provides a useful contrast with a sibling tool. Every word earns its place; no filler or redundancy.
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 the tool's simplicity (one optional parameter, output schema present, read-only annotation), the description covers purpose, scope, and the key distinction from a sibling. Nothing essential is missing for an AI agent to select and invoke it correctly.
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?
The input schema covers the single parameter response_format with 100% coverage, including an enum and default. The description adds nothing about this parameter, so the baseline of 3 applies — the schema does the heavy lifting and the description doesn't need to compensate.
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 clearly states it lists configured ZFS replication tasks, explains what these are in parentheses, and specifies the returned fields (direction, transport, enabled state, last-run state). It explicitly distinguishes from truenas_list_jobs, so it's specific and well-differentiated.
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?
The description gives an explicit when-not: 'Unlike truenas_list_jobs, this shows the task CONFIGURATION even when nothing is running.' This tells the agent when to choose this tool over a related alternative, which is exactly the kind of guidance needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List scheduled pool scrub tasks with their pool, schedule, threshold (minimum days between scrubs), and enabled state. Complements truenas_list_pools, which shows a scrub only while it's running.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| tasks | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, so the bar is lower. The description adds valuable context: it clarifies that it lists scheduled tasks (not currently running ones) and enumerates the returned fields. This goes beyond what annotations state, though it doesn't cover potential edge cases like empty results.
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?
Two tight sentences: the first gives the primary purpose and key output details, the second provides a useful distinction from a sibling tool. No wasted words or redundancy.
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?
The tool is simple with one optional parameter and an output schema. The description covers its scope, the relationship to a sibling, and the read-only nature is already in annotations. No significant gaps remain.
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?
The only parameter, response_format, is fully described in the schema with enum, default, and description, achieving 100% schema coverage. The tool description itself does not add additional parameter details, so the baseline of 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?
The description states exactly what it does: 'List scheduled pool scrub tasks' and specifies the attributes returned (pool, schedule, threshold, enabled state). It also differentiates it from truenas_list_pools by noting that the sibling only shows a scrub while running.
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?
The description explicitly mentions the sibling tool truenas_list_pools and its behavior, implying this tool is for viewing scheduled scrub configurations rather than active scrub activity. It could be more direct about when to choose this tool, but the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List TrueNAS services (SMB, NFS, SSH, iSCSI, ...) with running state and whether they start on boot.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Only services in this state | |
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| services | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows it is safe. The description adds that it returns running state and boot-start status, which is useful but does not disclose deeper behaviors like filtering or pagination; this matches the baseline for annotation-covered tools.
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 is a single, front-loaded sentence with no filler. It efficiently communicates the tool's purpose and key output fields.
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 simple read-only list tool with good annotations, an output schema, and fully documented parameters, the description is sufficient. It conveys the domain and output, while schema and annotations cover the remaining details.
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?
The input schema already provides 100% coverage with descriptions for both parameters (state and response_format), including enums and defaults. The description adds no extra meaning about parameters, so the baseline 3 applies.
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 uses the specific verb 'List' and identifies the resource as 'TrueNAS services' with examples (SMB, NFS, SSH, iSCSI), clearly distinguishing it from sibling list tools. It also states the output includes running state and boot-start status, making the purpose unambiguous.
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?
The description provides clear context that this tool is for listing services, and the examples indicate which kind of services, but it does not explicitly mention alternatives or when-not-to-use it. Since the scope is self-evident and no exclusions are stated, it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List ZFS snapshots with creation time and space used. Systems often have thousands of snapshots — filter by dataset and paginate. Works across TrueNAS versions (the underlying API differs; this tool picks the right one automatically).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum snapshots to return | |
| offset | No | Snapshots to skip, for pagination | |
| dataset | No | Only snapshots of this dataset (e.g. 'tank/appdata') | |
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| offset | Yes | |
| has_more | Yes | |
| snapshots | Yes | |
| next_offset | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the description does not need to restate that. It adds valuable behavioral context by noting that the tool 'Works across TrueNAS versions (the underlying API differs; this tool picks the right one automatically),' which is beyond the annotations and helps the agent trust the tool's compatibility.
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 is three sentences, front-loaded with the core purpose, and every sentence earns its place: what it lists, how to handle scale, and cross-version compatibility. No redundancy or filler.
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?
The description provides enough context for a list tool: purpose, usage guidance, and compatibility note. With a full output schema and read-only annotations, nothing critical is missing for the agent to invoke it correctly.
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?
The input schema has 100% coverage with descriptive parameter definitions (e.g., 'Maximum snapshots to return' for limit, 'Only snapshots of this dataset' for dataset). The description only reinforces the dataset filter and pagination advice without adding new syntax or format information, so it meets the schema-driven baseline.
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 uses a specific verb ('List') and a resource ('ZFS snapshots') and adds detail about the returned fields ('creation time and space used'), clearly distinguishing it from sibling tools that list other TrueNAS resources.
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?
The description gives clear context for when to use the tool ('Systems often have thousands of snapshots') and instructs to 'filter by dataset and paginate,' which serves as usage guidance. It does not explicitly exclude alternatives, but the sibling tools are distinct resources, so no exclusion is necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List configured periodic (automatic) snapshot tasks with their dataset, retention policy, schedule, and whether they're enabled. truenas_list_snapshots shows the snapshots that EXIST; this shows whether an automatic snapshot POLICY is actually running.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| tasks | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds clarity about what the tool reports (policy status, not existing snapshots), but does not disclose additional behavioral traits like pagination, ordering, or performance. This is adequate but not rich, matching the baseline for well-annotated read-only tools.
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?
Two well-structured sentences: the first states the exact scope and fields, the second differentiates from a sibling tool. Every sentence earns its place, no redundant 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?
This is a simple list operation with an optional format parameter. The output schema exists, so return values are already documented. The description fully explains what the tool does and how it differs from a similar tool, making it complete for the agent's selection and invocation needs.
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% (the only parameter, response_format, has a clear description). The description does not add anything beyond what the schema already provides, so the 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?
The description uses a specific verb ('List') and resource ('configured periodic snapshot tasks'), and enumerates the key fields returned (dataset, retention policy, schedule, enabled). It also explicitly distinguishes this tool from the sibling truenas_list_snapshots, making the purpose unambiguous.
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?
The description clearly states when to use this tool versus the alternative: 'truenas_list_snapshots shows the snapshots that EXIST; this shows whether an automatic snapshot POLICY is actually running.' This provides explicit guidance on tool selection and excludes the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List virtual machines with their run state, autostart, vCPU/memory allocation, bootloader, and a device summary (disk/NIC counts, whether a display is attached). Device details, including any VNC display password, are deliberately omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| response_format | No | markdown = compact human-readable summary; json = full structured data | markdown |
| Name | Required | Description |
|---|---|---|
| vms | Yes | |
| count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable context by deliberately noting that device details, including VNC display passwords, are omitted—an important behavior for security and expectation setting.
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?
Two sentences front-load the action and provide a complete summary of included fields and the deliberate omission. No redundant words or repetition of schema 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?
With an output schema present and a read-only list operation, the description covers the key return fields and notes the omitted sensitive details. This is sufficient for an agent to decide to call the tool and interpret results.
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?
The only parameter (response_format) is fully described in the schema with enum values and default; description coverage is 100%. The tool description adds no extra parameter meaning, matching the baseline of 3 for high schema coverage.
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 clearly states the tool lists virtual machines and enumerates the specific attributes returned (run state, autostart, vCPU/memory, bootloader, device summary). This distinguishes it from sibling list_* tools that target other resources like pools or disks.
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 context is implied by the tool name and description; it is evident this is for enumerating VMs. However, there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives for obtaining full device details, which would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0truenas_check_updatestruenas_connection_statustruenas_get_system_infotruenas_list_alertstruenas_list_appstruenas_list_cloudsync_taskstruenas_list_datasetstruenas_list_diskstruenas_list_jobstruenas_list_networktruenas_list_poolstruenas_list_replication_taskstruenas_list_scrub_taskstruenas_list_servicestruenas_list_sharestruenas_list_snapshot_taskstruenas_list_snapshotstruenas_list_vmsEvery tool targets a distinct TrueNAS resource (pools, datasets, alerts, disks, services, jobs, snapshots, VMs, etc.), with clear separation between existing resources and their scheduled task configurations (e.g., snapshots vs snapshot_tasks, jobs vs replication_tasks/cloudsync_tasks/scrub_tasks). The descriptions explicitly clarify potentially confusing pairs.
All tool names follow the same 'truenas_' prefix plus a verb_noun pattern (list_*, get_system_info, check_updates, connection_status). Naming is uniformly lowercase snake_case with consistent verbs, making it easy to predict tool names for new resources.
With 18 tools, the server is on the heavier side but justifiable for a comprehensive TrueNAS monitoring surface. Each tool covers a unique functional area, so none feel redundant. The count is slightly high but well within acceptable bounds for a full-featured NAS monitoring server.
As a read-only monitoring server, it covers all major TrueNAS operational areas: storage health (pools, datasets, snapshots, disks), services, networking, system info, alerts, jobs, VMs, apps, updates, and backup task configurations. Minor gaps exist (e.g., no single-item detail retrieval, no performance metrics), but these are workarounds via filters and pagination.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Read-only MCP server for turva.dev, an agent-readiness audit and advisory service.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/PainInTheNic/MCP-TrueNAS'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
