Skip to main content
Glama

Change a book's status

update_book_status
DestructiveIdempotent

Moves a book that is already in the reader's ReadingRate library to another status: "reading" (starts it today, or picks a stopped book back up), "read" (finishes it, with an optional rating and finish date), "stopped" (sets it aside today), or "want_to_read". A finished book stays finished: "reading" or "want_to_read" on it starts a re-read, a new reading after the finished one; "read" on it changes its rating and, with date_finished, its finish date; "stopped" is refused until a re-read is started. Starting, finishing or stopping a book takes it off the reader's queue (a book club entry stays). Asking for the status the book already has changes nothing. Marking a book read also adds it to the reader's ReadingRate activity feed. Other readers see that they finished it while the reader's profile is public and shows finished books (new accounts start private, and finished books start hidden): on the profile, and for people who follow the reader in their feed and on the book's page.

Use when the user says they started, finished, stopped or gave up a book in their library, wants to rate a finished book, or wants a book back on their want-to-read list. For a book not yet in their library, use add_book_to_library.

Examples:

  • {"book_id": "", "status": "reading"}

  • {"book_id": "", "status": "read", "rating": 5}

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>",
      "status": "<status>"
    },
    "name": "update_book_status"
  }
}

Input Schema

NameRequiredDescriptionDefault
ratingNoRating from 1 to 5, only with status "read"
statusYesThe new status
book_idYesThe book's ReadingRate id or its library entry id
date_finishedNoFinish date, YYYY-MM-DD, only with status "read" (default: today)

Output Schema

NameRequiredDescriptionDefault
bookNoThe book: id, slug, title, authors
ratingNoThe rating recorded, when finishing
messageYesHuman-readable result
successYesWhether the status changed
new_statusNoThe status after the change
old_statusNoThe status before the change
date_startedNoStart date, when the status is reading
date_finishedNoFinish date, when the status is read

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations, the description discloses the full status-transition state machine, including edge cases: a finished book only re-reads via "reading"/"want_to_read", "read" mutates rating and optionally finish date, and "stopped" is refused until a re-read starts. It also confirms the idempotentHint ("Asking for the status the book already has changes nothing"), explains the destructiveHint consequence (removal from the reader's queue, with the book-club exception), and notes the side effects on the activity feed and public-profile visibility.

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?

Purpose is front-loaded, followed by transition rules, then when-to-use and examples, so an agent can stop reading early. The profile-visibility sentence is dense and slightly buried mid-paragraph, and the whole definition is on the long side, but nearly every sentence carries operational meaning.

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 4-parameter mutation tool with a rich state machine, the definition covers preconditions, per-status behavior, refusals, side effects, and an explicit alternative tool. Return values are covered by the existing output schema, so no explanation of the response shape is required.

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 100%, so the baseline is 3, but the description goes further by defining what each enum value does in domain terms ("reading" starts today or resumes a stopped book, "stopped" sets aside today, "read" finishes with optional rating and finish date). It also clarifies that date_finished changes an already-finished book's finish date, which the schema's "only with status read" phrasing does not spell out.

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 first clause gives a specific verb and resource ("Moves a book that is already in the reader's ReadingRate library to another status") and enumerates the four target statuses. It is immediately distinguishable from add_book_to_library, which is explicitly named as the tool for books not yet in the library.

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 usage paragraph lists concrete trigger phrases ("started, finished, stopped or gave up", "wants to rate a finished book", "wants a book back on their want-to-read list") and names the alternative tool with the exact condition that selects it ("For a book not yet in their library, use add_book_to_library"). When-not guidance is also present via the refusal rules for a stopped finished book.

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.