Skip to main content
Glama

List Books

list_books
Read-onlyIdempotent

BROWSES/FILTERS THE CATALOG by metadata (canonical author via author_id, title/author/summary words via search, language, category, year range, translation recency) — no page-text matching. PICK THIS to see WHAT EXISTS by an author or in a tradition, or to enumerate a date range. Returns books with title, author (string + canonical author_id + author_url), language, year, translation progress, and is_first_translation (the site's First Translation flag; filter with first_translation=true; a researched claim that can be wrong, so say "flagged as"). → For a relevance-ranked topic search use search_library; for passages on a theme use search_translations (exact words) or search_concept (by meaning). To answer "do you hold X?" call check_duplicate: a listing that misses a title is not evidence of absence.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_books"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNo
limitNoMax results (default 100, max 200)
offsetNoPagination offset. When truncated is true, call again with next_offset; a full page is not the whole holding (default 0).
searchNoRelevance-ranked word match over title (original, display and English), author, original-script name forms (e.g. Greek), AND the book's AI summary. A hit can name your term in neither title nor author, only in what the book discusses. Diacritic-insensitive. For exactly one person's books use author_id instead.
work_idNoEvery witness of one WORK, across editions, languages and centuries — pass the work_id from a result row or from get_book. Use this instead of a title search whenever you already hold the identifier: witnesses of one work are often titled differently in each language, so a title search finds only the subset that happens to share your wording. Unlike list_editions (which returns the whole set), this composes with language, year_from/year_to and sort.
year_toNoLatest edition year (inclusive).
categoryNoSubject category. "first-translation" is accepted as an alias for first_translation=true.
languageNo
author_idNoCanonical author slug, e.g. "jan-hus" — filters to exactly that person's books via the author thesaurus (variant slugs resolve to the canonical person). Every book row in results carries its author_id; the response echoes the canonicalized author.
year_fromNoEarliest edition year (inclusive). Matches only books with a known numeric year — ~60% of the library.
edition_keyNoOther digitizations of ONE printing — pass the edition_key from a result row. Only full-quality keys match on both sides, so this answers "what other scans of this exact edition do you hold?" and never merges different printings of the same title.
has_editionNoISO code — return only books READABLE in that language, e.g. "es". Different from `language`, which is the language printed on the leaves of the scan: a Latin book with a Spanish edition matches language="Latin" AND has_edition="es". Each result then also carries url_localized.
first_translationNoOnly books carrying the site's "First Translation" flag (same filter as the website). A researched claim, not a proof; get_book returns the status and evidence.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / category / description
      Added value: +"Subject category. \"first-translation\" is accepted as an alias for first_translation=true."
    • addedInput schema / properties / first_translation
      Added value: +{
      +  "description": "Only books carrying the site's \"First Translation\" flag (same filter as the website). A researched claim, not a proof; get_book returns the status and evidence.",
      +  "type": "boolean"
      +}
  2. Changed1 schema field changed
    • addedInput schema / properties / offset
      Added value: +{
      +  "description": "Pagination offset. When truncated is true, call again with next_offset; a full page is not the whole holding (default 0).",
      +  "type": "number"
      +}
  3. Changed1 schema field changed
    • changedInput schema / properties / search / description
      Previous value: -"Free-text filter matching title or author (relevance-ranked, may include title matches). For exactly one person's books use author_id instead."New value: +"Relevance-ranked word match over title (original, display and English), author, original-script name forms (e.g. Greek), AND the book's AI summary. A hit can name your term in neither title nor author, only in what the book discusses. Diacritic-insensitive. For exactly one person's books use author_id instead."
  4. Changed1 schema field changed
    • addedInput schema / properties / work_id
      Added value: +{
      +  "description": "Every witness of one WORK, across editions, languages and centuries — pass the work_id from a result row or from get_book. Use this instead of a title search whenever you already hold the identifier: witnesses of one work are often titled differently in each language, so a title search finds only the subset that happens to share your wording. Unlike list_editions (which returns the whole set), this composes with language, year_from/year_to and sort.",
      +  "type": "string"
      +}
  5. Changed1 schema field changed
    • addedInput schema / properties / edition_key
      Added value: +{
      +  "description": "Other digitizations of ONE printing — pass the edition_key from a result row. Only full-quality keys match on both sides, so this answers \"what other scans of this exact edition do you hold?\" and never merges different printings of the same title.",
      +  "type": "string"
      +}
  6. Changed4 schema fields changed
    • addedInput schema / properties / author_id
      Added value: +{
      +  "description": "Canonical author slug, e.g. \"jan-hus\" — filters to exactly that person's books via the author thesaurus (variant slugs resolve to the canonical person). Every book row in results carries its author_id; the response echoes the canonicalized author.",
      +  "type": "string"
      +}
    • changedInput schema / properties / search / description
      Previous value: -"Filter by title or author"New value: +"Free-text filter matching title or author (relevance-ranked, may include title matches). For exactly one person's books use author_id instead."
    • addedInput schema / properties / year_from
      Added value: +{
      +  "description": "Earliest edition year (inclusive). Matches only books with a known numeric year — ~60% of the library.",
      +  "type": "number"
      +}
    • addedInput schema / properties / year_to
      Added value: +{
      +  "description": "Latest edition year (inclusive).",
      +  "type": "number"
      +}
  7. Changed1 schema field changed
    • addedInput schema / properties / has_edition
      Added value: +{
      +  "description": "ISO code — return only books READABLE in that language, e.g. \"es\". Different from `language`, which is the language printed on the leaves of the scan: a Latin book with a Spanish edition matches language=\"Latin\" AND has_edition=\"es\". Each result then also carries url_localized.",
      +  "type": "string"
      +}
  8. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare this a safe, idempotent, closed read, so the bar is lower, yet the description still adds real behavioral context: the first_translation flag is disclosed as 'a researched claim that can be wrong' that must be hedged as 'flagged as', and a listing miss 'is not evidence of absence'. It also previews the return fields, though pagination/truncation semantics live only in the schema.

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: the operation and its boundary come first, then the use case, then the alternative routing via arrows. It is dense and close to over-packed with parentheticals, but every clause carries information an agent needs, and nothing is repeated from the schema verbatim.

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 13-parameter tool with no output schema, the definition covers scope, alternatives, return shape, and two reliability caveats that could otherwise cause bad answers. An agent has everything it needs to choose and call this correctly.

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?

With 85% schema coverage the baseline is 3, but the description adds framing the schema lacks — that author_id resolves through a canonical thesaurus, that year filters only match the ~60% with known years, and that translation recency is a sortable dimension. It stops short of explaining limit/offset behavior, deferring fully 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?

States a specific verb and resource ('browses/filters the catalog by metadata') and immediately bounds it with 'no page-text matching'. The parenthetical enumerates the exact filter facets (author_id, search, language, category, year range, translation recency), so an agent can distinguish it from search_library or search_translations without opening a 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 explicit positive selection criteria ('PICK THIS to see WHAT EXISTS by an author or in a tradition, or to enumerate a date range') and names three alternatives with the conditions that select them: search_library for relevance-ranked topics, search_translations for exact passages, search_concept for meaning. It even routes the 'do you hold X?' question to check_duplicate.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.