Search the public SansFiction catalog (no auth). Returns JSON { query, searchType, count, books[] }; each book includes id (the catalog UUID used as book_id by every other tool), slug, title, and authors. When to use: your entry point for discovery — resolve a title/author/ISBN into a book_id. Use search_my_library instead to search only the signed-in user's own shelves; use get_book once you already have an id/slug and want full details.

Get full public metadata for a single book by catalog UUID or slug. Returns { book } (title, authors, description, editions, series, identifiers). Returns a 404 error if not found. When to use: you already have a book_id or slug and need details/editions. If you only have a title or author, call search_books first to obtain the id.

Get a book series and its ordered volumes by series UUID. Returns { series } including the volume list with positions. Returns a 404 error if the series is unknown. When to use: to enumerate every volume in a series and their reading order. Obtain series_id from a book's series metadata via get_book or search_books — this tool does not accept a name.

List public, curated collections (no auth). Returns { count, collections[] } with id, name, and description. Page through results with limit + offset. When to use: browse editorially curated public collections available to everyone. For the signed-in user's OWN collections, use list_my_collections instead.

List books on the authenticated user's shelves, most-recently-updated first. Returns { count, books[] } where each entry has status, current_page, percent, rating, and book metadata. When to use: browse or enumerate the user's library, optionally filtered by shelf. To find a specific title within the library use search_my_library; for the public catalog use search_books. Requires SANSFICTION_TOKEN (a bearer token from https://sansfiction.com/docs/agents).

Add a catalog book to the user's library. Idempotent upsert — calling again with a different status moves the book to that shelf rather than erroring. When to use: put a catalog book (book_id from search_books) onto a shelf for the first time. To edit an existing entry's status/rating/review/progress use update_library_book; to take a book off entirely use remove_book_from_library. Requires SANSFICTION_TOKEN (a bearer token from https://sansfiction.com/docs/agents).

Update one or more fields of a book already in the library. Supply any subset — only the fields you pass change. Special behavior: current_page records a reading-progress log entry (this is what feeds get_reading_stats), and setting rating or review publishes that entry publicly. Returns the updated row; errors with 404 if the book is not in the library (add it first). When to use: change fields or log progress for a book ALREADY on a shelf. Add it first with add_book_to_library; remove it with remove_book_from_library. Requires SANSFICTION_TOKEN (a bearer token from https://sansfiction.com/docs/agents).

Remove a book from the user's library entirely (all shelves). Idempotent — removing a book that is not present is a no-op. When to use: permanently take a book out of the library. If you only want to change its shelf (e.g. mark 'dnf' or 'read'), use update_library_book instead — do not remove and re-add. Requires SANSFICTION_TOKEN (a bearer token from https://sansfiction.com/docs/agents).

Full-text search restricted to the user's own library (matches book title and subtitle). Returns { count, books[] } with status and rating. When to use: find a specific book the user already owns. For catalog-wide discovery use search_books; to list everything on the shelves (optionally by status) use list_my_books. Requires SANSFICTION_TOKEN (a bearer token from https://sansfiction.com/docs/agents).

List the user's own collections. Returns { count, collections[] } (id, name, description, visibility). When to use: the signed-in user's OWN collections. For editorially curated public collections available to everyone, use list_public_collections instead. Requires SANSFICTION_TOKEN (a bearer token from https://sansfiction.com/docs/agents).

Reading statistics for a time range, matching the app's Stats page. Choose the range in ONE of two ways: (a) scope + date — e.g. scope='monthly', date='2026-03-15' covers that whole month; or (b) an explicit from+to pair, which OVERRIDES scope/date when both are given. Returns { range:{start,end}, booksFinishedCount, totalPagesRead, dailyAverage, logsCount, logs? }. dailyAverage is computed only for monthly/yearly scopes (null for weekly and for explicit from/to ranges). When to use: aggregate metrics (pages read, books finished, averages) over a period. To list the underlying books use list_my_books; to record progress that feeds these numbers use update_library_book with current_page. Requires SANSFICTION_TOKEN (a bearer token from https://sansfiction.com/docs/agents).