Skip to main content
Glama
kristianedlund

hardcover-mcp

by kristianedlund
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

set_user_book

DestructiveIdempotent

Add a book to your library or update your entry for it: status, rating, review, privacy, private notes, edition, and whether you own it.

Instructions

Add a book to your library or update your entry for it: status, rating, review, privacy, private notes, edition, and whether you own it. Upsert: creates the entry if the book isn't in your library yet, otherwise overwrites only the fields you pass (null leaves a field as it is; clearing one isn't supported). owned=true/false marks ownership of edition_id (or of the entry's current edition if edition_id is omitted; errors if there is none); passing edition_id also makes it the edition you're reading. Ownership changes are idempotent. Returns user_book_id, status, privacy, user_rating, edition_id, and owned/owned_changed when owned was given. Use set_user_book_read for start/finish dates and progress, set_list_book for custom lists, and delete_user_book to remove the book.

Input Schema

NameRequiredDescriptionDefault
ownedNotrue/false: you own (or no longer own) edition_id, or the current edition if edition_id is omitted.
ratingNoYour rating (e.g. 4.0, 3.5); returned as user_rating. Omit to leave unchanged.
statusNoReading status.
book_idYesHardcover book ID.
privacyNoWho can see it: 'public', 'followers', or 'private' (or 1, 2, 3).
edition_idNoEdition ID (from get_book). Sets which edition you're reading.
review_rawNoPlain-text review content (converted to Slate format).
reviewed_atNoISO date of the review (e.g. '2025-06-01').
private_notesNoPrivate notes visible only to you.
review_has_spoilersNoWhether the review contains spoilers.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.0.0
    • changedInput schema / properties / privacy / description
      Previous value: -"Privacy setting: 'Public', 'Followers', or 'Private' (or numeric ID 1/2/3)."New value: +"Who can see it: 'public', 'followers', or 'private' (or 1, 2, 3)."
    • changedInput schema / properties / rating / description
      Previous value: -"Rating (e.g. 4.0, 3.5). Omit to leave unchanged."New value: +"Your rating (e.g. 4.0, 3.5); returned as user_rating. Omit to leave unchanged."
    • changedInput schema / properties / status / description
      Previous value: -"Status name (e.g. 'Read') or numeric ID (1-5)."New value: +"Reading status."
    • addedInput schema / properties / status / enum
      Added value: +[
+  "Want to Read",
+  "Currently Reading",
+  "Read",
+  "Paused",
+  "Did Not Finish",
+  "Ignored"
+]
  2. Changed2 schema fields changedv0.9.0
    • changedInput schema / properties / edition_id / description
      Previous value: -"Edition ID (from get_edition). Sets which edition you're reading."New value: +"Edition ID (from get_book). Sets which edition you're reading."
    • addedInput schema / properties / owned
      Added value: +{
+  "description": "true/false: you own (or no longer own) edition_id, or the current edition if edition_id is omitted.",
+  "type": "boolean"
+}
  3. First observedv0.4.0

TDQS

A4.6/5.0
Behavior4/5

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

Goes well past the annotations: it explains that null leaves a field untouched, that clearing a field is NOT supported, the cross-field side effect of edition_id on the reading edition, the error case when no edition exists, and which fields are echoed back. That is exactly the kind of hidden behavior an agent needs before a destructive upsert. It stops short of five only because the destructiveHint consequence (what a mistaken overwrite actually costs) is implied rather than stated.

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?

Front-loaded with the operation and the field list, then the upsert rule, then the tricky owned/edition_id case, then sibling routing — a sensible ordering. It is dense with nested parentheticals, though, and a bulleted split of the owned semantics would read faster.

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?

Ten parameters, one required, no output schema — yet the description covers mutation semantics, the null-vs-clear rule, cross-field effects, an error condition, and the return fields. Nothing needed to call this 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 already 100%, so baseline is 3; the description earns more by documenting the interaction between owned and edition_id (ownership of the given edition, falling back to the current edition, erroring if none) and the rating-to-user_rating rename. The remaining parameters are left to the schema.

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+resource ('Add a book to your library or update your entry') and immediately pins the operation type as an upsert. It enumerates the exact fields under scope and distinguishes itself from the read/list/delete siblings by name.

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 routes three adjacent concerns to other tools: set_user_book_read for dates/progress, set_list_book for custom lists, delete_user_book for removal. The when-to-use question is answered without requiring the agent to compare schemas.

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

Deploy Server

Other Tools