Skip to main content
Glama

Source Library

by io.github.Embassy-of-the-Free-Mind
OverviewDiscussionsAdmin

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, and translation progress. → 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.

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).
categoryNo
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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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"
+}
  2. 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."
  3. 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"
+}
  4. 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"
+}
  5. 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"
+}
  6. 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"
+}
  7. First observed

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds genuinely non-structured behavior: no page-text matching, the exact return fields (title, author string + author_id + author_url, language, year, translation progress), and the caveat that an empty listing is not proof of absence. It stops short of discussing result volume or rate behavior, so it is strong but not exhaustive.

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?

Front-loaded with the verb and scope, then when-to-use, then return shape, then sibling routing, then the absence caveat — each sentence carries distinct information with no restatement of the name. The caps and arrow separators are loud but function as scan anchors rather than filler.

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 12-parameter, all-optional read tool with no output schema, the description covers purpose, selection, return fields, and the main semantic pitfalls (metadata-only, partial year coverage handled in schema). Nothing an agent needs to invoke it correctly is missing.

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 75%, but the description compensates where the schema is thin — notably the undocumented sort enum, which it glosses as 'translation recency' alongside year range, and it names the filter axes (canonical author via author_id, search words, language, category). The schema itself already carries rich per-parameter guidance (work_id vs title search, has_edition vs language), so this is additive rather than duplicative.

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 the scope with 'no page-text matching', which separates it from the passage/topic search siblings. It enumerates the filter dimensions and the returned fields, so an agent knows exactly what class of operation this is without opening the 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?

Explicitly says when to pick it ('to see WHAT EXISTS by an author or in a tradition, or to enumerate a date range') and routes three named alternatives with their selecting conditions: search_library for relevance-ranked topics, search_translations/search_concept for passages, check_duplicate for 'do you hold X?'. It even warns that a miss here is not evidence of absence — a usage trap an agent would otherwise fall into.

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

All Source Library toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources