Skip to main content
Glama

List a book's editions

list_book_editions
Read-onlyIdempotent

Lists the known editions of a book in the reader's ReadingRate library (publisher, year, pages, ISBN, language and translators, cover) and says which edition the reader's current reading is in. Each reading of a book can be in its own edition: a re-read in another translation has its own pages, cover and translator, and earlier readings keep theirs. Use when the reader says which edition, translation or printing they are reading, starts a re-read in another one, or asks which editions ReadingRate knows. Then ask them to pick one and call update_book_edition with its edition_id; if theirs is not listed, ask for the ISBN printed on the back or the copyright page (or a photo of the barcode, whose digits you read) and call update_book_edition with isbn. To start a re-read first, use update_book_status with status "reading". Examples:

  • {"book_id": ""}

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "book_id": "<book_id>"
    },
    "name": "list_book_editions"
  }
}

Input Schema

NameRequiredDescriptionDefault
book_idYesThe book's ReadingRate id or slug, or its library entry id

Output Schema

NameRequiredDescriptionDefault
bookYesThe book: id, slug, title
editionsYesThe known editions: edition_id, publisher, year, pages, isbn_13, format, language, translators, cover_url, current
translationsNoThe book's known translations: translation_id, language, translators, original (true for the original language); pass translation_id to update_book_edition with an ISBN
current_readingNoThe reading the edition applies to: reading_id, reading_number (2 for a first re-read), status, edition_id (null when none is named)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint false, so the safety profile is covered; the description goes well beyond that by explaining the per-reading edition model (each reading keeps its own pages, cover and translator, and earlier readings retain theirs). That domain rule is not derivable from any structured field and materially affects how the agent interprets results.

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?

Well front-loaded — capability first, then when-to-use, then the follow-up workflow, then an example. Slightly redundant in the sentence about re-reads in another translation, which restates the per-reading edition point twice ("its own pages, cover and translator" and "earlier readings keep theirs").

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 single-parameter read tool with an output schema and full annotation coverage, nothing an agent needs is missing: trigger conditions, interpretation of multi-edition readings, the downstream mutation call, and the ISBN fallback path are all present.

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 100% for the single book_id parameter, which already documents that a ReadingRate id, slug, or library entry id is accepted. The description only reinforces this with an example payload and the phrase "The book's ReadingRate id," adding no new format or constraint detail. Baseline 3 is appropriate when the schema carries the load.

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 and resource: "Lists the known editions of a book in the reader's ReadingRate library," then enumerates the returned fields (publisher, year, pages, ISBN, language, translators, cover) and adds a second function the sibling tools don't cover (identifying the edition the current reading is in). An agent can distinguish it from update_book_edition and update_book_status purely from this text.

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 trigger conditions (reader names an edition/translation/printing, starts a re-read in another edition, or asks which editions exist) and a named next step: pick an edition and call update_book_edition with edition_id. It also supplies a concrete fallback when the edition isn't listed — request the ISBN from the back cover or copyright page, or a barcode photo — and routes that to update_book_edition with isbn, plus a sequencing note to call update_book_status with status "reading" for a re-read.

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.