Skip to main content
Glama

kavita_volume

Destructive

Retrieve, create, update, or delete Kavita volumes via the self-hosted server API; write actions need explicit confirmation, and omitting it returns a dry-run preview.

Instructions

kavita_volume covers the volume toolset (4 operations). Auth is the x-api-key header, or a JWT from KAVITA_USERNAME and KAVITA_PASSWORD. Self-hosted Kavita only. action help with target returns one action's parameters. Writes need confirm set to the boolean true and KAVITA_ALLOW_WRITES=true. Omit confirm for a dry-run preview that sends nothing. Destructive, credential, or exposure actions add an extra warning in the preview and here: delete, scan, analyze, refresh, cache clear, cleanup, user or role changes, Auth Key create or revoke, password reset, settings, license, scrobbling tokens, OAuth or OIDC, and email. Actions: delete, get, post_multiple, post_update.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "kavita_volume"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyNoJSON body for the Kavita operation. Secrets are redacted in output.
queryNoOpenAPI query parameters.
actionYesKavita operation to call, or help.
paramsNoOpenAPI path parameters, such as seriesId.
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

A3.7/5.0
Behavior5/5

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

Annotations already flag destructive/openWorld/non-idempotent, and the description adds substantial context beyond them: the x-api-key or JWT auth path, self-hosted-only constraint, the confirm=true plus KAVITA_ALLOW_WRITES=true gate, the dry-run preview that sends nothing, and an explicit list of which actions trigger extra warnings. This is exactly the behavioral detail an agent needs before invoking a destructive tool.

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

Conciseness3/5

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

The resource and auth are front-loaded, which is good, but the middle is a dense run-on and the long enumeration of destructive actions (delete, scan, analyze, refresh, cache clear, cleanup, user/role changes, Auth Key, password reset, settings, license, scrobbling tokens, OAuth/OIDC, email) is verbose and partly redundant with the destructiveHint annotation.

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

Completeness3/5

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

For a 6-parameter, nested-object, destructive tool with no output schema, the description covers auth, write gating, dry-run, and warnings well, but leaves the actual semantics of each action (what delete removes, what get returns, what post_multiple vs post_update do) entirely unexplained, which is a meaningful gap for an agent choosing an action.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents action, target, confirm, body, query, and params. The description restates the confirm and target semantics without adding format or syntax detail beyond the schema, so the baseline 3 applies.

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?

The description names the resource ('kavita_volume covers the volume toolset') and enumerates the four operations plus help, which distinguishes it from siblings like kavita_series or kavita_library. However, the actions are generic CRUD labels (delete, get, post_multiple, post_update) and it never says what a volume is or what each action operates on, so the purpose is clear at the resource level but not at the operation level.

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

Usage Guidelines3/5

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

It gives useful procedural guidance: use 'action help with target' to discover an action's parameters, set confirm=true to execute, omit confirm for a dry-run. But it offers no guidance on when to choose this tool over the sibling tools (e.g., series vs volume vs chapter), and no explicit when-not conditions.

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