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, author/title fragment via search, language, category, year range, translation recency) — no content/topic 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).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sortNo
limitNoMax results (default 100, max 200)
searchNoFree-text filter matching title or author (relevance-ranked, may include title matches). 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 / 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"
+}
  2. 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"
+}
  3. 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"
+}
  4. 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"
+}
  5. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds value by clarifying that this tool performs metadata filtering only, not content/topic matching, and by describing the returned book fields. There is no contradiction with the annotations.

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?

The description is three compact sentences that front-load the core capability, then add selection criteria, return shape, and routing to alternatives. The all-caps emphasis is somewhat noisy but does not create redundancy; every sentence earns its place.

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?

For an 11-parameter list tool with no output schema and many siblings, the description covers what the tool does, when to use it, what it returns, and which alternatives handle adjacent cases. It relies appropriately on the schema for detailed parameter semantics; minor gaps around controlled vocabularies and pagination keep it just short of fully complete.

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 73% schema description coverage, the schema already documents most parameters in detail, including nuanced guidance for work_id and has_edition. The description adds a useful conceptual layer by grouping parameters into metadata categories and explaining author_id canonicalization. Minor omissions such as the exact values for category and language are not fully compensated, but the overall semantic guidance is strong.

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 description opens with 'BROWSES/FILTERS THE CATALOG by metadata' and enumerates the specific metadata dimensions (author, title fragment, language, category, year range, translation recency), then explicitly contrasts with 'no content/topic matching.' This makes the resource and verb clear while distinguishing it from search_library, search_translations, and search_concept.

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?

The description gives direct when-to-use instructions: 'PICK THIS to see WHAT EXISTS by an author or in a tradition, or to enumerate a date range.' It also lists exclusions with arrows to the correct alternatives for relevance-ranked topic search and passage search, and parameter descriptions reinforce when to use work_id vs title search and has_edition vs language.

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