calibre-mcp

Overview Schema Source Related Servers Discussions Admin

Build semantic index

calibre_build_index

Idempotent

Builds a searchable semantic or keyword-only index for selected Calibre books, enabling accurate search and retrieval across their content.

Instructions

Build the semantic index for specific books (required: bookId, ids, or query — full-library indexing is deferred). A query selects ALL matching books (no 100-book cap); a call still working after ~45 s returns a "still running" status (not an error) while the build keeps committing in the background — re-run the same call to get its result; only one build runs per library at a time, and up-to-date books are skipped. Extracts, chunks, and embeds each book. Set keywordOnly=true (or when the embedding model is absent, it happens automatically) to build a keyword-only index that powers mode:"keyword" search with zero ML dependencies. Re-run after adding books; use force to re-index unchanged ones. Set prune=true to also drop index entries for books that no longer exist in the library (removals/merges leave searchable orphans behind).

Input Schema

Name	Required	Description	Default
`ids`	No
`force`	No
`prune`	No
`query`	No
`bookId`	No
`library`	No
`enableFts`	No
`keywordOnly`	No

Output Schema

Name	Required	Description	Default
`chunks`	No
`figures`	No
`failures`	No
`booksDone`	No
`elapsedMs`	No
`indexedIds`	No
`bookDetails`	No
`keywordOnly`	No
`prunedBooks`	No
`booksIndexed`	No
`booksSkipped`	No
`prunedChunks`	No
`runningBuild`	No
`stillRunning`	No
`prunedFigures`	No
`booksPreserved`	No
`booksRefreshed`	No
`booksRequested`	No
`semanticReason`	No
`semanticAvailable`	No
`backgroundBuildFailed`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.12.0Oct 31, 2026

addedOutput schema / properties / backgroundBuildFailed
```
Added value: +{
+  "type": "boolean"
+}
```
addedOutput schema / properties / booksDone
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / booksRefreshed
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / indexedIds

Added value: +{
+  "items": {
+    "type": "number"
+  },
+  "type": "array"
+}

addedOutput schema / properties / runningBuild

Added value: +{
+  "enum": [
+    "this",
+    "other"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / stillRunning
```
Added value: +{
+  "type": "boolean"
+}
```

Changed1 schema field changedv0.10.0Oct 28, 2026
- addedOutput schema / properties / booksPreserved
```
Added value: +{
+  "type": "number"
+}
```
First observedv0.7.2Jul 29, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Goes far beyond the annotations: discloses the ~45 s 'still running' non-error status and the re-run pattern, background committing, single-build-per-library concurrency, skipping of up-to-date books, and the automatic keywordOnly fallback when the embedding model is absent. These are exactly the non-obvious traits an agent needs to avoid misinterpreting a timeout as a failure.

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-loaded with the selector requirement before the operational caveats, and nearly every clause adds distinct information. It is a single dense paragraph that runs long, and a bulleted split between selection, timeout behavior, and index options would read faster.

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?

An output schema exists, so return shapes are rightly omitted, and the description nonetheless covers the async/timeout contract and pruning semantics. The only substantive holes are the undocumented 'library' and 'enableFts' parameters, which an agent must guess at.

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 0%, so the description carries the burden and mostly does: it explains the bookId/ids/query selector triplet with 'full-library indexing is deferred', query's no-cap behavior, force, prune, and keywordOnly. It leaves 'library' and 'enableFts' completely undefined, which for an 8-parameter tool is a real gap.

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?

Opens with a specific verb+resource ('Build the semantic index for specific books') and immediately scopes the target with the required selector set. It is unambiguously distinct from the search/index-consumer siblings like calibre_semantic_search.

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

Usage Guidelines5/5

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

Explicitly covers when to use force ('re-index unchanged ones'), when to use prune ('drop index entries for books that no longer exist'), when to use keywordOnly ('powers mode:"keyword" search'), and the normal re-run-after-adding-books case. Effectively names the alternative search mode rather than leaving it to inference.

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

Deploy Server