Skip to main content
Glama

add_document

DestructiveIdempotent

Publish markdown as an EPUB book in Kavita's Reports library; reusing an existing title replaces that book and keeps reading progress.

Instructions

Build an EPUB from markdown and put it in the Kavita library "Reports".

Publishing a title that already exists replaces that book (same folder, same Kavita series, reading progress kept); a new title is a new book. Images only as data: URIs (base64, up to 1 MiB each); any other image (a URL or a path) becomes its alt text. No tags. Returns the series ID when Kavita already has the book or scan_now found it; otherwise Kavita lists it in about 6 minutes. To move a book to another collection, use update_document.

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": {
      "markdown": "<markdown>",
      "title": "<title>"
    },
    "name": "add_document"
  }
}

Input Schema

NameRequiredDescriptionDefault
titleYesBook title, up to 200 characters. The same title replaces the same book.
authorNoAuthor shown in Kavita and on the e-readerClaude
summaryNoShort description shown in Kavita
languageNoLanguage code, e.g. en or sven
markdownYesThe document, in markdown. Headings become the table of contents.
scan_nowNoAsk Kavita to scan the Reports library now (seconds) instead of waiting for its folder watcher (about 6 minutes). Needs an admin Kavita key.
collectionNoKavita collection to put the book in (reused by name, created if new)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations (destructiveHint=true, idempotentHint=true) it explains exactly what destruction means: the same title replaces that book in the same folder and series while keeping reading progress, and a new title creates a new book. It also discloses image handling rules (data URIs only, up to 1 MiB each, otherwise alt text), that no tags are written, and that scan_now needs an admin Kavita key.

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

Conciseness5/5

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

The purpose is front-loaded in the first sentence, followed by tightly grouped facts about replacement, images, and return timing. There is no filler; every clause conveys behavior an agent would otherwise have to guess.

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

Completeness5/5

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

For a seven-parameter write tool with no output schema, the description covers the important unknowns: what gets replaced, reading-progress preservation, image limitations, return value and the six-minute visibility caveat, and the admin-key prerequisite. An agent can call this correctly and set expectations without further information.

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 schema already documents all seven parameters, but the description adds real meaning: the image constraints apply to the markdown parameter, scan_now trades seconds for the ~6 minute folder-watcher wait and requires an admin key, and title identity drives replacement. It never mentions author, language, summary, or collection defaults, which are left entirely to the schema.

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

Purpose5/5

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

The first sentence names a specific verb (Build an EPUB) plus the exact destination library (the Kavita library "Reports"), which no sibling covers. It also contrasts itself with update_document for the related but different task of moving a book between collections.

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 makes clear this is the create/publish path and points to update_document when the intent is moving an existing book, which is the most likely ambiguity among siblings. It does not spell out conditions where you should prefer, say, delete_document or get_document, but those are obviously different operations.

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