Skip to main content
Glama

kavita_readinglist

Destructive

Manage Kavita reading lists and reading progress: create, update, delete lists, add or remove items, export CBL, and track next/previous chapters via MCP operations.

Instructions

kavita_readinglist covers the readinglist toolset (27 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, get_all_people, get_info, get_items, get_lists_for_chapter, get_lists_for_series, get_name_exists, get_next_chapter, get_people, get_prev_chapter, post_all, post_create, post_delete_item, post_delete_multiple, post_export_as_cbl, post_lists, post_promote_multiple, post_regenerate_cover, post_remove_read, post_update, post_update_by_chapter, post_update_by_multiple, post_update_by_multiple_series, post_update_by_series, post_update_by_volume, post_update_position.

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_readinglist"
  }
}

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.8/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety bar is partly covered; the description nonetheless adds real substance: credential requirements, the two-step dry-run-then-confirm write protocol, and an explicit list of categories that trigger an extra warning. Some of that list (scan, analyze, refresh, cache clear, cleanup, license, scrobbling, OAuth) does not correspond to any action in this toolset, which looks like inherited template text and slightly muddies the signal. It does not contradict the annotations.

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 structure is sensible and front-loaded: toolset identity, auth, write-safety, dry-run, then the action list. However, a long enumeration of destructive categories that do not exist in this readinglist toolset (scan, analyze, cache clear, license, OAuth, email) is dead weight that dilutes the warning. The single-paragraph action dump is also harder to scan than a grouped list.

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 27-action dispatcher with no output schema and no per-action documentation, the description covers auth, mutation safety, dry-run semantics, and the help-based discovery escape hatch, which is the minimum an agent needs to call it without guessing. What it omits is what the generic get*/post_* prefixes mean and what the tool actually returns or how much data a get_items call produces. The boilerplate destructive-action list slightly reduces confidence that the described behaviors map to this specific toolset.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description earns above baseline by explaining that 'help' with target is the way to obtain per-action parameters — critical given that params, query, and body are generic open maps whose valid contents vary by action. It also clarifies that confirm must be the boolean true and cannot be false or the string 'true', reinforcing the schema's const constraint with the rejection behavior. It adds only that extra env-var prerequisite and discovery workflow.

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 states that this tool covers the readinglist toolset with 27 operations and enumerates every action name, so an agent can tell it manages Kavita reading lists rather than libraries, series, chapters, or persons named in the sibling list. The verb-level purpose is implied by the action names rather than stated outright ('create, read, update, and delete reading lists'), which keeps it short of a 5.

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?

It gives concrete operating context: self-hosted Kavita only, x-api-key or JWT via KAVITA_USERNAME/KAVITA_PASSWORD auth, and that 'action help with target returns one action's parameters' — which is the key discovery path for 27 opaque actions. It also explains the write flow (confirm=true plus KAVITA_ALLOW_WRITES=true) and that omitting confirm yields a dry-run preview. It does not say when to choose this over siblings such as kavita_series or kavita_collection, so no explicit exclusion guidance is present.

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