calibre-mcp

Overview Schema Source Related Servers Discussions Admin

Search books

calibre_search

Read-only

Find books in a Calibre library by title, author, ISBN, tag, Calibre query syntax, or full text; search within one book for snippets or return only result counts.

Instructions

Find books by exact title, author, ISBN, tag, or Calibre query syntax (mode=meta), or by full text (mode=fts). scope=book returns short keyword snippets from inside one book; first hits often land in TOC/front matter — for definitional or topic questions within a book prefer calibre_semantic_search scope=book (ranked passages with char offsets). Use calibre_semantic_search for meaning/topic queries. For "how many" questions use countOnly=true (returns only the count). filter accepts a bundle name to scope the search (list bundles via calibre_manage_bundles).

Input Schema

Name	Required	Default
`mode`	No	meta
`sort`	No
`limit`	No
`query`	Yes
`scope`	No	library
`bookId`	No
`cursor`	No
`filter`	No
`library`	No
`countOnly`	No
`sortOrder`	No
`include_excluded`	No

Output Schema

Name	Required	Description	Default
`hits`	No
`mode`	No
`count`	No
`query`	No
`scope`	No
`total`	No
`bookId`	No
`filter`	No
`offset`	No
`bookIds`	No
`nextCursor`	No
`exclusionsApplied`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.10.0Oct 28, 2026

addedOutput schema / properties / hits

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "bookId": {
+        "type": "number"
+      },
+      "snippet": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "snippet"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed4 schema fields changedv0.7.3Aug 18, 2026

addedInput schema / properties / filter

Added value: +{
+  "maxLength": 256,
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / include_excluded
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / exclusionsApplied

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

addedOutput schema / properties / filter
```
Added value: +{
+  "type": "string"
+}
```

First observedv0.7.2Jul 29, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds real behavioral detail, warning that scope=book returns short keyword snippets whose first hits often land in TOC/front matter. It also explains that countOnly returns only a count. It omits pagination behavior despite a cursor parameter.

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 core purpose and modes, then layered routing advice; each sentence carries usable information. It is dense but not padded, though the scope=book caveat is embedded mid-sentence rather than separated.

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-value explanation is unnecessary, and the description covers the key decision points for a 12-parameter tool. It stops short of describing cursor-based pagination and multi-library scoping, which matter for a search tool with these parameters.

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 0%, so the description must carry the load; it adds meaning for mode, scope, filter, countOnly and bookId context. However, of 12 parameters, sort, sortOrder, limit, cursor, library and include_excluded are never addressed, leaving the pagination and scoping semantics entirely to the bare 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?

States a specific verb (find) plus the resource (books) and enumerates the searchable fields and the two operating modes (meta vs fts). It explicitly distinguishes itself from calibre_semantic_search, so an agent can route without opening either schema.

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?

Gives concrete when-to-use rules: mode=meta for metadata fields, mode=fts for full text, calibre_semantic_search for meaning/topic queries, countOnly=true for 'how many' questions. It also names the sibling alternative and the condition that selects it.

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

Deploy Server