Shelfclub

Get book details

get_book

Read-onlyIdempotent

Look up one book in the ShelfClub catalog, by its ShelfClub id or by ISBN. Returns its description, authors, reader rating, series, an edition (ISBN, page count, publisher, publication date, language), its shelfclub.app link, and its mood, vibe, pace and genre tags (machine-generated, or voted for by at least three readers of the book). A lookup by id also returns the ShelfClub author id of each author that has an author record, and which of the moods, vibes and pace readers of the book voted for, with how many did. These tools do not return content warnings: if asked, say so, and do not infer them from the tags or present anything as ShelfClub's.

Input Schema

Name	Required	Description	Default
`id`	No	The ShelfClub id of the book, as the other tools return it. Give this or `isbn`, not both.
`isbn`	No	An ISBN-10 or ISBN-13, with or without hyphens.

Output Schema

Name	Required	Description
`book`	No
`status`	Yes	"try_again_later": the service was busy and looked nothing up, so the other fields are absent.
`tagProvenance`	No	Where the moods, vibes, pace and genres come from.
`retryAfterSeconds`	No	With "try_again_later", when known: how long to wait.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 13, 2026

changedInput schema / properties / id / description

Previous value: -"The Shelfclub id of the book, as the other tools return it. Give this or `isbn`, not both."New value: +"The ShelfClub id of the book, as the other tools return it. Give this or `isbn`, not both."

changedOutput schema / properties / book / properties / authorLinks / description

Previous value: -"The authors that have a Shelfclub author record. Present when the book was looked up by id, not by ISBN."New value: +"The authors that have a ShelfClub author record. Present when the book was looked up by id, not by ISBN."

changedOutput schema / properties / book / properties / authorLinks / items / properties / id / description
```
Previous value: -"The Shelfclub id of the author."New value: +"The ShelfClub id of the author."
```

changedOutput schema / properties / book / properties / id / description

Previous value: -"The Shelfclub id of the book."New value: +"The ShelfClub id of the book."

Changed1 schema field changedOct 11, 2026

addedOutput schema / properties / book / properties / readerTags

Added value: +{
+  "additionalProperties": false,
+  "description": "Which of the book's moods, vibes and pace at least `minimum` readers of the book voted for, and how many did. A mood, vibe or pace of the book that is not named here is machine-generated only. Present when the book was looked up by id, not by ISBN.",
+  "properties": {
+    "minimum": {
+      "description": "How many readers of a book must vote for a mood, vibe or pace before it is put on the book.",
+      "type": "number"
+    },
+    "moods": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "alsoFromCatalog": {
+            "description": "True when the tag is machine-generated as well. False when the readers' votes are all that puts it on the book.",
+            "type": "boolean"
+          },
+          "readers": {
+            "description": "How many readers of the book voted for it.",
+            "type": "number"
+          },
+          "tag": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "tag",
+          "readers",
+          "alsoFromCatalog"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "pace": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "alsoFromCatalog": {
+              "description": "True when the tag is machine-generated as well. False when the readers' votes are all that puts it on the book.",
+              "type": "boolean"
+            },
+            "readers": {
+              "description": "How many readers of the book voted for it.",
+              "type": "number"
+            },
+            "tag": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "tag",
+            "readers",
+            "alsoFromCatalog"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "vibes": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "alsoFromCatalog": {
+            "description": "True when the tag is machine-generated as well. False when the readers' votes are all that puts it on the book.",
+            "type": "boolean"
+          },
+          "readers": {
+            "description": "How many readers of the book voted for it.",
+            "type": "number"
+          },
+          "tag": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "tag",
+          "readers",
+          "alsoFromCatalog"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "minimum",
+    "moods",
+    "vibes",
+    "pace"
+  ],
+  "type": "object"
+}

First observedOct 9, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description discloses the returned fields, the asymmetry between id and ISBN lookups (author ids and vote counts only on id), and how tags are produced (machine-generated or voted by at least three readers). The content-warning prohibition with an explicit 'do not infer, do not present as ShelfClub's' rule is exactly the kind of non-obvious behavioral constraint an agent cannot get from 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?

Front-loaded with the verb and resource, then the return shape, then the lookup-mode difference, then the content-warning rule. Some sentences are long and list-heavy, but no sentence is filler and the ordering prioritizes what matters.

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?

Covers what is returned, how it differs by lookup key, how tags are sourced, and how to handle an adjacent question the tool cannot answer. Even with an output schema present, nothing needed to call it 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 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the consequence of each key: an id lookup returns additional data (author ids, vote tallies) that an ISBN lookup does not, which affects parameter choice.

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?

States a specific verb (look up) and resource (one book in the ShelfClub catalog) and names the two keys accepted. This is clearly a single-record fetch, distinguishable from sibling lookups like search_books and find_books_by_mood.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It specifies the two lookup keys and, via the schema, the mutual exclusivity. It also gives explicit behavioral guidance on content warnings ('if asked, say so, and do not infer them'), which is real usage direction. It stops short of naming when to prefer this over search_books, but the single-record framing makes the choose clear enough.

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

All Shelfclub tools Inspect

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

Need Help?