siftivo

Add a book to my library

add_to_library

DestructiveIdempotent

Shelve, rate or update one book for the linked reader: want to read (NOT_STARTED), READING, FINISHED or DNF, with the day it happened, a rating in half stars, or a private note. Suits "add X to my list", "I finished X on Sunday" and "just finished X, four and a half stars" (one call: FINISHED, 4.5). Where they are in a book (a page, or time left on audio) is write_journal. Each field sent replaces the reader's own value, so send only what they asked to change; without readingStatus the book stays on its shelf, and a rating alone on a book not on a shelf saves the rating without shelving it. Notes are private: a public review is write_review. For favorites or a list of books read, save_my_taste. Needs a linked Siftivo account.

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": {
      "workId": "<workId>"
    },
    "name": "add_to_library"
  }
}

Input Schema

Name	Required	Description
`date`	No	The day they started (READING), finished (FINISHED) or stopped (DNF), YYYY-MM-DD in their time zone. Omit for today, or for a book shelved after the fact.
`notes`	No	The reader's own note on the book, private to them
`rating`	No	Stars, 0.5 to 5 in half-star steps
`workId`	Yes
`visibility`	No	Who can see the book on their shelves: EVERYONE, or ONLY_ME to keep it off every surface other people reach. Omit to leave it as it is.
`readingStatus`	No	The shelf to put the book on. Omit to leave it where it is, or NOT_STARTED for a book the reader has not opened yet.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 9, 2026

addedInput schema / properties / date

Added value: +{
+  "description": "The day they started (READING), finished (FINISHED) or stopped (DNF), YYYY-MM-DD in their time zone. Omit for today, or for a book shelved after the fact.",
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

removedInput schema / properties / progress

Removed value: -{
-  "description": "Percent read, 0 to 100",
-  "maximum": 100,
-  "minimum": 0,
-  "type": "integer"
-}

Changed1 schema field changedOct 21, 2026

addedInput schema / properties / visibility

Added value: +{
+  "description": "Who can see the book on their shelves: EVERYONE, or ONLY_ME to keep it off every surface other people reach. Omit to leave it as it is.",
+  "enum": [
+    "EVERYONE",
+    "ONLY_ME"
+  ],
+  "type": "string"
+}

Changed4 schema fields changedOct 4, 2026
- changedInput schema / properties / rating / description
```
Previous value: -"Whole stars, 1 to 5"New value: +"Stars, 0.5 to 5 in half-star steps"
```
- changedInput schema / properties / rating / minimum
```
Previous value: -1New value: +0.5
```
- addedInput schema / properties / rating / multipleOf
```
Added value: +0.5
```
- changedInput schema / properties / rating / type
```
Previous value: -"integer"New value: +"number"
```

Changed2 schema fields changedOct 3, 2026

removedInput schema / properties / readingStatus / default
```
Removed value: -"NOT_STARTED"
```

addedInput schema / properties / readingStatus / description

Added value: +"The shelf to put the book on. Omit to leave it where it is, or NOT_STARTED for a book the reader has not opened yet."

First observedSep 8, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only flag destructive/idempotent/open-world; the description adds the crucial replace semantics ("Each field sent replaces the reader's own value, so send only what they asked to change"), the omission behavior without readingStatus, and the subtle case where a rating alone on an unshelved book saves the rating without shelving. It also states the auth prerequisite ("Needs a linked Siftivo account") and the privacy boundary of notes. This is well beyond what the structured fields convey.

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 action and shelves, then alternatives, then edge cases — a sensible priority order with no filler sentences. It is dense and long for a single paragraph, but nearly every clause carries distinct routing or behavioral information, so little is wasted.

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 6-parameter mutation tool with no output schema, the description covers the write semantics, omission defaults, the rating-without-shelf edge case, account requirement and sibling routing. Nothing an agent needs to invoke it correctly appears 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 83%, so the schema carries most parameter documentation. The description still adds interpretive meaning: it explains half-star granularity in natural language, frames date as the day an event happened, and clarifies that omitting readingStatus leaves the shelf untouched rather than resetting it — semantics the enum alone 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?

Opens with a specific verb set plus resource: "Shelve, rate or update one book for the linked reader", then enumerates the exact shelves (NOT_STARTED, READING, FINISHED, DNF), the date, the half-star rating and the private note. It explicitly distinguishes itself from write_journal, write_review and save_my_taste, so an agent can route without opening any 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?

Gives concrete trigger utterances ("add X to my list", "I finished X on Sunday", "just finished X, four and a half stars") and even shows how one utterance maps to a single call: FINISHED plus 4.5. It also routes competing intents away: progress goes to write_journal, public reviews to write_review, favorites and read-lists to save_my_taste.

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

All siftivo 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?