Skip to main content
Glama
si-essence

audiobookshelf

by si-essence
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

abs_items

Destructive

Manage Audiobookshelf library items: fetch, edit metadata, covers, tracks, and chapters; run scans, matches, batch updates, and deletions with dry-run previews and confirm-gated writes.

Instructions

abs_items covers the items toolset (18 operations). Auth is Authorization Bearer from ABS_API_TOKEN. Self-hosted Audiobookshelf only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and ABS_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive or credential actions add an extra warning in the preview: delete, scan, match, purge, backup restore, user changes, API key create or revoke, password, and settings. Actions: delete_by_id, delete_cover, delete_file, get_by_id, get_ffprobe, get_metadata_object, patch_cover, patch_ebook_status, patch_media, patch_tracks, post_batch_delete, post_batch_get, post_batch_quickmatch, post_batch_scan, post_batch_update, post_chapters, post_match, post_scan.

Input Schema

NameRequiredDescriptionDefault
bodyNoJSON body for the Audiobookshelf operation. Secrets are redacted in output.
queryNoQuery parameters.
actionYesAudiobookshelf operation to call, or help.
paramsNoExpress path parameters, such as id.
targetNoWith action help, the action whose parameters to describe.
confirmNoSet to the boolean true to execute the write. Omit this field for a dry-run preview. false and the string true are rejected.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior5/5

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

Annotations already mark it destructive/non-readonly, and the description adds substantial context: Bearer auth from ABS_API_TOKEN, self-hosted-only scope, the write gate requiring ABS_ALLOW_WRITES, dry-run preview behavior, and a specific list of actions that trigger extra warnings (delete, scan, purge, backup restore, key/secret actions). This materially exceeds what the annotations convey.

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-loads the toolset scope and auth, then adds behavioral constraints and the action list. Dense but every sentence carries information; the long action enumeration is necessary for a dispatcher tool.

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

Completeness4/5

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

With no output schema and a mutation-capable tool, the description covers auth, dry-run safety, destructive warnings, help discovery, and the full action set. Return-value format is left undescribed, a minor gap for a complex 18-action router.

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 baseline is 3, but the description usefully clarifies confirm semantics (only boolean true accepted, string rejected, omit for preview) and the target/help relationship, adding meaning beyond the schema.

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

Purpose4/5

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

States it 'covers the items toolset (18 operations)' for Audiobookshelf and enumerates all actions, making the resource domain clear. It's distinguishable from siblings like abs_authors or abs_series by the explicit action list, though the top-line framing is broad.

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?

Explains the help+target pattern to discover per-action parameters, and clearly states that writes require confirm=true plus ABS_ALLOW_WRITES=true while omitting confirm yields a dry-run. No explicit when-to-use-this-vs-sibling guidance beyond the resource domain, but operationally strong.

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