Skip to main content
Glama

Set the edition of a reading

update_book_edition
DestructiveIdempotent

Sets which edition the reader's current reading of a book is in: one of the book's known editions (edition_id, from list_book_editions), or the edition with an ISBN (isbn: 10 or 13 digits, as printed on the book or read from a photo of its barcode). An ISBN ReadingRate does not know yet is looked up in Open Library and added as an edition of the book, checked to be this book, and other readers can then pick it too; give translation_id (from list_book_editions) when you know whose translation it is. The reading's page count follows the edition unless the reader typed their own, and its cover follows unless they chose one. Earlier readings keep their own edition. clear: true clears the edition. Use after list_book_editions, when the reader has said which edition they hold. To start a re-read first, use update_book_status with status "reading". Examples:

  • {"book_id": "", "edition_id": ""}

  • {"book_id": "", "isbn": "9780679772835", "translation_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": "update_book_edition"
  }
}

Input Schema

NameRequiredDescriptionDefault
isbnNoThe ISBN-10 or ISBN-13 of the reader's copy, instead of edition_id
clearNotrue clears the reading's edition instead of setting one
book_idYesThe book's ReadingRate id or slug, or its library entry id
edition_idNoA known edition's id from list_book_editions
translation_idNoWith isbn: whose translation the copy is, a translation_id from list_book_editions

Output Schema

NameRequiredDescriptionDefault
addedNoTrue when the ISBN was new to ReadingRate and its edition was added
pagesNoThe reading's page count after the change, when known
editionNoThe edition now set: edition_id, publisher, year, pages, isbn_13, language, translators, cover_url; absent when cleared
messageYesHuman-readable result
successYesWhether the reading's edition was set
reading_idNoThe reading whose edition was set
reading_numberNoWhich reading of the book it is (2 for a first re-read)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedOutput schema / properties / edition / description
      Previous value: -"The edition now set: edition_id, publisher, year, pages, isbn_13, language, translators, cover_url; null when cleared"New value: +"The edition now set: edition_id, publisher, year, pages, isbn_13, language, translators, cover_url; absent when cleared"
    • changedOutput schema / properties / pages / description
      Previous value: -"The reading's page count after the change"New value: +"The reading's page count after the change, when known"
  2. Added

TDQS

A5/5.0
Behavior5/5

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

Annotations already declare non-readOnly, destructive, idempotent, and openWorld behavior, but the description adds substantial detail beyond them: unknown ISBNs are looked up in Open Library, validated as this book, and added for other readers. It also explains side effects on page count and cover, and that earlier readings retain their own edition.

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?

The description is front-loaded with the core operation, then procedurally covers ISBN lookup, translation behavior, page-count and cover side effects, and clearing. The examples at the end are directly useful, and despite the length every sentence carries operational detail for a complex mutation.

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 destructive, open-world mutation with five parameters, it supplies prerequisites, alternatives, side effects, clearing behavior, and examples. Since an output schema exists, the description does not need to explain return values, and together the definition is complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the input schema has 100% description coverage, the description adds operational meaning: ISBN can be printed or read from a barcode photo, may be unknown and then looked up, and translation_id should be supplied when the translation is known. It also clarifies that clear=true removes the edition rather than merely modifying it.

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 a specific verb and resource: changing which edition a reader's current reading of a book is in. It clearly distinguishes setting a known edition by edition_id from adding an ISBN-based edition, and names the sibling list_book_editions for lookup. An agent can identify the operation 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?

It explicitly says to use this after list_book_editions and when the reader has said which edition they hold, and it names update_book_status with status "reading" for starting a re-read first. The clear=true path and the ISBN-vs-edition_id choice are both explained, so the agent has concrete routing guidance.

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.