ReadingRate

Adds one book to the reader's ReadingRate library. It goes on the want-to-read list unless a status is given: "reading" for a book they are reading now, "read" for one they have finished (with an optional rating and finish date), or "stopped". Use when the user asks to add a book to their library or reading list, or says they are reading or have finished a book that is not in their library yet. Identify the book with exactly one of book_id, isbn or title_author. A book already in the library is left where it is, and the result says which shelf it is on; to move it, use update_book_status. A book added as read also goes on 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). A book given by title and author that is not in the ReadingRate catalog is looked up in Google Books and added to the catalog, which is public, and ReadingRate then analyzes it; so add a book named by title only once the reader has confirmed the title. Examples: - {"title_author": {"title": "The Great Gatsby", "author": "F. Scott Fitzgerald"}} - {"isbn": "9780140449136", "status": "read", "rating": 5} - {"book_id": "<book id>", "status": "reading"}

Adds up to 40 books to the reader's ReadingRate library in one call, by ReadingRate book id, all on the same shelf (want-to-read unless a status is given). Books already in the library are left where they are and listed. Use after lookup_books_batch has matched a photographed shelf or a list, and the reader has said which of the matched books to add. Books added as read also go on the reader's ReadingRate activity feed; other readers see that they finished them while the reader's profile is public and shows finished books (new accounts start private, and finished books start hidden). It takes ids only, so it never adds a book to the catalog; a book lookup_books_batch could not match is added with add_book_to_library once the reader confirms its title. Example: {"book_ids": ["<book id>", "<book id>"], "status": "read"}

Writes the reader's note on one line of a poem to their ReadingRate notes: a reading, a connection, a reaction. The line is not saved as a quote. Use when the reader wants to record a thought about a specific line of a poem. To save the line itself as a quote, use save_poem_line. Each call adds a new note. Example: {"anchor": "wyatt/whoso-list-to-hunt/13", "note": "The hunt as courtship, and its exhaustion."}

Sets two or three books side by side and shows them as a comparison grid. Aspects: "difficulty" (overall and per-dimension scores, and each book's hardest and easiest dimensions), "themes" (shared and distinct), "length" (word count and reading time), "style" (primary genre and literary regard) and "awards". Use when the user asks to compare specific books, which of them is harder or longer, or which to read first. For a single book, use get_book_details. To find books, use search_books. Default aspects: difficulty, themes, length. Examples: - {"book_ids": ["crime-and-punishment", "the-brothers-karamazov"]} - {"book_ids": ["1984", "brave-new-world", "fahrenheit-451"], "aspects": ["themes", "difficulty"]}

Permanently deletes one reading insight the reader saved in ReadingRate, with the conversation record attached to it. It cannot be undone. A copy the reader's Notion already received stays in their Notion, and the result says so. Use when the reader asks to delete or forget an insight they saved. Find its id with get_reading_notes, and confirm with the reader which insight they mean before deleting. Example: {"insight_id": "<insight id>"}

Finds the quotes and notes in the reader's ReadingRate collection that are closest in meaning to one of their saved quotes or notes, across all their books, with each passage's book, author, page and a similarity score from 0 to 1. Use when the reader asks what else they have saved that connects to a particular quote or note, or for related passages in their collection. Get the id from list_saved_quotes (a quote) or get_reading_notes (a note). Examples: - {"id": "<quote id>", "type": "quote"} - {"id": "<note id>", "limit": 10, "threshold": 0.35}

Lists the winners, shortlists and longlists of the literary prizes ReadingRate tracks, grouped by year, newest first. The prizes include the Booker Prize, the International Booker Prize, the Pulitzer Prize for Fiction, the National Book Award, the Nobel Prize in Literature, the Women's Prize for Fiction, and the Hugo and Nebula awards. It also holds canonical lists, such as the Modern Library 100, and the set texts of national school curricula and exam boards. Each book links to its ReadingRate analysis. Use when the user asks who won or was shortlisted for a literary prize, for prize-winning books from a range of years, or which books a list or a school syllabus names. It holds results only, not news about a prize or the organization behind it. source_type picks the kind of source: "award" for prizes, "list" for canonical lists and publisher series, "curriculum" for school curricula and exam boards. Without it, prizes and lists come back and curricula do not. Each book's award_type and award_kind say which kind of source it came from. A curriculum sets a book for study; it is not a prize the book won. Examples: - {"award": "Booker Prize", "category": "winner", "limit": 10} - {"award": "Pulitzer", "year_min": 2020, "year_max": 2024} - {"year_min": 2023, "year_max": 2023, "category": "winner"} - {"award": "AQA", "source_type": "curriculum"}

Describes one of the reader's ReadingRate book clubs: its description, how many members it has and their usernames and roles, and its five most recent books. Use when the reader asks about a particular club of theirs: who is in it, or what it has read. Get club_id from list_book_clubs. Example: {"club_id": "<club id>"}

Returns the book one of the reader's ReadingRate clubs is reading now, with its reading schedule: each milestone's pages, due date and discussion questions. Use when the reader asks what their club is reading, how far they should be by now, or for the discussion questions. Get club_id from list_book_clubs. Example: {"club_id": "<club id>"}

Gives one book's full ReadingRate analysis and shows its difficulty profile as a radar chart: nine difficulty dimensions and four literary-regard dimensions, each scored 0 to 100 with a written reason, plus the book's description, genres, themes, word count, reading time, authors, awards and editions. awards holds prizes and canonical lists; taught_in holds the school curricula and exam boards that set the book, which are not awards. Use when the user asks how hard a specific book is, what makes it difficult, how long it takes to read, whether it has won prizes, or for details about it. To find books that match a description, use search_books. To set two or three books side by side, use compare_books. Identify the book with exactly one of book_id, slug or title_author. Difficulty dimensions: vocabulary_complexity, syntactic_complexity, abstraction_level and information_density (how hard the prose is); narrative_indirection, symbolic_density, ironic_distance, resolution_withholding and structural_complexity (how hard the meaning is). Regard dimensions: canonical_status, critical_acclaim, literary_influence, author_standing. Examples: - {"slug": "crime-and-punishment"} - {"title_author": {"title": "The Great Gatsby", "author": "Fitzgerald"}} - {"slug": "beloved", "include_similar": true} - {"slug": "war-and-peace", "include_time_estimate": true}

Lists the books the reader is reading now, from their ReadingRate library: current page, percent complete, pages left, and the hours left at their own logged reading pace. Also lists poems they have recently read again, with how many times. Use when the user asks what they are reading, how far along they are in a book, or how long a book they are reading will take them to finish. For books they have finished or want to read, use get_reading_history.

Returns today's connections in the reader's reading: passages from different books they are reading, and from their saved quotes and notes, that share a theme, with the theme named and a question to reflect on. The first call each day creates them: ReadingRate sends a few of those passages to its AI provider to name the theme and write the question, then stores the result in the reader's account and counts it against their ReadingRate AI usage. Later calls the same day return the same connections. Use when the reader asks what connects their recent reading, or for today's reading connections or reflection prompt.

Returns ReadingRate's summary of one calendar month of the reader's reading: books finished, time and pages read, the difficulty of what they read, highlights, and how the month compares with the year so far. Summaries are made after each month ends. Use when the reader asks how a particular month of reading went. For any other range of dates, such as a year or a season, use summarize_reading_period. Example: {"year": 2026, "month": 9}

Returns passages of text from a book the reader is reading, taken from the pages just before their current position in ReadingRate, with their progress in the book. It finds the book and the page itself, so the reader does not have to name the chapter. With a topic, it returns the passages near their position that are closest to that topic. Use when the reader asks for help with what they just read: the last chapter, a passage they did not understand, or what the author meant in the part they have reached. To search a whole book for a topic, use search_book_content. Text is available only for books the reader uploaded their own copy of in the ReadingRate app. For other books the result says the text is not available; the book's scores and analysis are in get_book_details. Examples: - {} - {"book_id": "<book id>", "topic": "the argument about metempsychosis"}

Recommends books from the ReadingRate catalog for this reader, matched to the difficulty range they usually read, the genres and themes they return to, and their reading pace, with the reasons for each pick and a reading-time estimate at their pace. Books they have already finished are left out. It can draw only from their want-to-read list, leave out genres, or reach a little above their usual difficulty. Use when the reader asks what to read next, or which books would suit them. Examples: - {} - {"from_tbr": true} - {"difficulty_stretch": true, "exclude_genres": ["Horror"]}

Returns the text of a poem in the ReadingRate collection, with numbered lines. Titles, epigraphs, dedications and stage directions are marked apart from the verse. A long work in sections, such as an epic, returns its list of sections unless a section number is given. Use when the user asks to read or see a specific poem, or part of one. It returns only poems already in the collection; it does not write, continue or translate poems. Examples: - {"identifier": "wyatt/whoso-list-to-hunt"} - {"identifier": "milton/paradise-lost", "section": 1}

Shows how widely the reader has read poetry in ReadingRate, by poetic form (sonnet, ode, ...), by era and by poet: distinct poems read, total reads and a mastery stage for each. Use when the reader asks which forms of poetry they have read, or how their poetry reading spreads across eras and poets.

Summarizes the reader's poetry reading in ReadingRate: the poems they keep returning to, ranked by how often and how recently they read each one, with read counts and last-read dates; how many lines they know by heart; and whether they read widely or reread deeply. Use when the reader asks which poems they keep coming back to, how much poetry they read, or how many lines they know by heart. Example: {"limit": 10}

Lists the page the reader reached on each day of one reading of a book in their ReadingRate library: for each day, the furthest page, the page they left off at, the pages read and the percent of their copy. Use when the user asks how far they got each day, how many pages they read on which days, how long a book took them day by day, or wants a chart of their progress through a book. For the books themselves, their status and dates, use get_reading_history. ReadingRate records each change of page from the time this history began, so days before logged_since are unknown, not unread. Days are counted in timezone: give the reader's IANA time zone when known (for example "Europe/London"); otherwise their notification setting is used, else UTC. Examples: - {"book_id": "<book id>"} - {"book_id": "<book id>", "timezone": "Europe/London"} - {"book_id": "<book id>", "reading_number": 1}

Describes the reader's progress in one reading domain in ReadingRate: their mastery stage, books, words and hours read, quotes and reflections, and what the next stage requires. Use when the reader asks about their progress in a particular genre, culture, period or theme, or what it takes to reach the next stage. Get domain_id from list_reading_domains. Example: {"domain_id": "<domain id>"}

Shows the reader's yearly book goal from ReadingRate and their progress toward it: books finished, books left, whether they are on track, the pace needed, and books finished per month. When no goal is set, it says so and suggests one from their past reading. It does not set a goal. Use when the user asks how they are doing on their reading goal, whether they are on track, or how many books they have read this year.

Lists the books in the reader's ReadingRate library with their status (read, reading, want to read, stopped), rating, start and finish dates, and the reader's own reflection, newest activity first. Use when the user asks what they have read or finished, what is on their want-to-read list, how they rated a book, or which of a set of books they have already read. Filter with status. Set include_sessions to add the reading sessions logged for each book.

Returns what the reader has noted about their reading in ReadingRate: their highlights and notes, insights ReadingRate generated about their reading, and the reading insights they saved, each with its id. Pass book_id for one book's notes, or insight_query to get the saved insights closest to a topic, from any book. Use when the reader asks what they thought or noted about a book, for their highlights, what they concluded in an earlier discussion, or which saved insight to delete. To search the text of a book, use search_book_content. Examples: - {"book_id": "<book id>"} - {"insight_query": "unreliable narrators"}

Summarizes the reader's ReadingRate reading record: reading speed from their logged sessions, the difficulty range they usually read, their most-read genres and themes, books per month, and how they rate books. Use when the user asks how fast they read, what difficulty suits them, what genres or themes they read most, or how their ratings are spread.

Returns written insights about how the reader's reading has been changing: genres they are exploring, authors they return to, their pace, and how their themes are shifting. When none are current, ReadingRate generates them first: it sends the reader's past year of finished books (titles, authors, genres, themes, ratings and dates) to its AI provider, stores the new insights in the reader's account for seven days in place of the earlier ones, and counts the generation against the reader's ReadingRate AI usage. Generating takes several seconds and happens at most once a day. Use when the reader asks about their reading patterns, trends or trajectory. For numbers such as pace and genres, use get_reading_stats.

Returns the top of one of the ranked book lists published on readingrate.com: the highest-ranked books from a country, in an original language, of a genre or on a subject, by women or by men, or at a difficulty. With no filter it returns ReadingRate's curated canon of 100, ranked by hand. Every other list is computed from literary-regard scores (canonical status, critical acclaim and influence), not readers' votes. Each answer gives the list's page address. Use when the user asks for the top, greatest or most important books of a country, a language, a genre, a period or a theme, for a ranked reading list, or for the hardest or easiest great books. For books matching a search, use search_books; for prize results, use get_award_winners. Filters combine: {"country": "Japan", "author_gender": "female"} ranks books by Japanese women. A country or language with no list page is still ranked when the catalog holds books from it, and the answer says how many books the list holds. Examples: - {"country": "Japan", "limit": 10} - {"country": "Nigeria"} - {"language": "Russian", "genre": "short-fiction"} - {"subject": "death-mortality"} - {"subject": "victorian-19th-century-literature", "author_gender": "female"} - {"difficulty": "hardest", "limit": 5} - {}

Lists the ReadingRate book clubs the reader belongs to, with their role in each and the book each club is reading now. Use when the reader asks about their book clubs or what their clubs are reading. For one club's members and past books, use get_book_club; for its current book's schedule and discussion questions, use get_book_club_current_read.

Lists the reader's saved quotes and memorized poem passages that are due for review today in ReadingRate's spaced-repetition practice, earliest first, with how many poem lines they know by heart. Use when the reader asks to be quizzed on their quotes or passages, what is due for review, or how many lines they know by heart. After the reader answers, grade each one with record_quote_review. Example: {"limit": 5}

Lists the reading domains (genres, cultures, periods and themes) the reader has made progress in through ReadingRate, with their mastery stage in each (newcomer, exploring, well read, analytical, expert), books completed and time spent. Up to 50 domains, the deepest first. Use when the reader asks what areas they have read deeply in, what they know most about, or how their domain progress looks. For one domain's full metrics and what the next stage needs, use get_reading_domain. For poetic forms, use get_poetic_form_mastery.

Lists the quotes and passages the reader has saved in ReadingRate, newest first, with page, speaker, notes and themes. Can be narrowed to one book or to quotes containing given words. Use when the user asks for their saved quotes or highlights, or for what they saved from a particular book. Example: {"book_id": "<book id>", "search": "memory"}

Records that the reader read a poem from the ReadingRate collection, adding one read to its count. Poems the reader returns to often rank higher in get_poetry_reading_stats, and recent reads can feature in their daily reading connections. A work in sections, such as an epic, is logged one section at a time. Use when the reader says they read or reread a poem, or asks to mark one as read. Each call adds one more read. Examples: - {"identifier": "wyatt/whoso-list-to-hunt"} - {"identifier": "milton/paradise-lost", "section": 1}

Logs reading for a book in the reader's ReadingRate library: pages read, the page they reached, or a note. It sets the book's current page, adds the pages to today's entry in their reading journal, and adds the note to that entry. One journal entry per book per day: a second call the same day extends that day's pages and appends the note. A book on the want-to-read list moves to reading. Use when the user says how many pages they read, which page they are on, or wants a thought about today's reading saved with it. For a book not yet in their library, use add_book_to_library first. Give pages_read (pages read since the last log), current_page (the arabic page reached) or roman_page (a page of an introduction or preface numbered in roman numerals), only one of them; a note can be sent alone. Each call logs again, so do not repeat a call that succeeded. Introductions numbered i, ii, iii… count. When the reader says their copy's introduction runs to a roman page (for example lx), send front_matter_ends_on with it, alone or with the page; the copy keeps it, and later arabic pages count after it. "0" means the copy has none, or the reader skipped it, which takes its pages back out. Examples: - {"book_id": "<book id>", "pages_read": 30} - {"book_id": "<book id>", "current_page": 150} - {"book_id": "<book id>", "front_matter_ends_on": "lx", "roman_page": "liv"} - {"book_id": "<book id>", "notes": "The argument only lands once you have read the footnotes."}

Matches a list of books to the ReadingRate catalog in one call, from ISBNs, titles, or titles with authors, and returns each match's ReadingRate analysis with a confidence level (exact, high, medium, low). Matching tolerates misspellings, such as titles read off book spines in a photo. A book the catalog does not hold is looked up in Open Library, a public book database, and comes back unmatched with what Open Library knows about it. Use when the user gives several books at once, such as a photographed bookshelf or a pasted list, and wants them identified, ranked or compared. For a single book, use get_book_details. Takes up to 20 books per call, more on some accounts; a longer list returns an error that gives the limit, so split it. Example: {"books": [{"isbn": "9780140449136"}, {"title": "Crime and Punishment", "author": "Dostoevsky"}, {"title": "The Brothers Karamazov"}]}

Records how well the reader recalled one saved quote or poem passage during review, on a 0 to 5 scale, and reschedules its next review: good recall pushes the next review further out, poor recall brings it back soon. It replaces the item's previous schedule. Use when the reader has answered a review question from list_quotes_due_for_review and says, or it is clear, how well they remembered it. Grades: 0 no memory at all; 1 wrong, but remembered on seeing it; 2 wrong, but it felt familiar; 3 right with serious difficulty; 4 right after hesitation; 5 perfect. Each call records one review, so grade an item once per review. Example: {"quote_id": "<quote id>", "quality": 4}

Saves one line of a poem to the reader's ReadingRate quotes, tied to its exact place in the poem, with an optional note. Saved lines appear with their other quotes and come up in quote review. Use when the reader asks to save, keep or remember a line of a poem. To write a note about a line without saving it as a quote, use annotate_poem_line. Each call saves the line again, so save a line once. Example: {"anchor": "wyatt/whoso-list-to-hunt/13"}

Saves a passage the reader asks to keep to their ReadingRate quotes, under a book in their library, with optional page, speaker, notes and themes. Saved quotes also appear in the ReadingRate app and in quote review. Use when the user asks to save, keep or remember a quote or passage from a book. For a line of a poem, use save_poem_line. Each call adds a new quote, so calling twice saves it twice. Example: {"book_id": "<book id>", "quote_text": "124 was spiteful.", "page_number": 1}

Saves a reading insight to the reader's ReadingRate account: a short summary and the key takeaways, in the reader's terms, about one or more books in their library, with optional topics. It is stored with those books, appears in their ReadingRate journal, comes back in later conversations through get_reading_notes, and is copied to the reader's Notion if they have connected Notion to ReadingRate. Only the fields below are sent; nothing else from the conversation is. Use only when the reader asks to save or keep something from the discussion. Show them the summary and takeaways first and save once they agree. Each call saves a new insight, so save a discussion once; the reader can remove one with delete_reading_insight. Example: {"book_ids": ["<book id>"], "summary": "Humbert's eloquence works on the reader as a defense brief.", "key_insights": ["The prose's beauty is a manipulation", "The reader is cast as the jury"], "topics": ["unreliable narration"]}

Searches the text of one book or one poem for passages about a topic, by meaning rather than exact words, and returns the passages with page and chapter (books) or the line and its neighbours (poems), plus a relevance score. Use when the user asks to find a passage, a scene, or what a book or poem says about something, in a book or poem already identified by id (from search_books, get_reading_history or get_currently_reading). For the text around the page the reader has reached, without a topic, use get_passages_near_reading_position. Book text is available only for books the reader uploaded their own copy of in the ReadingRate app; for other books the result says the text is not available. Poems are always searchable. Spoiler protection is on by default for books: for a book on the reader's want-to-read list no passages are returned, and for a book they are reading only pages up to their logged position are searched. If no position is logged, the whole book is searched, unless spoiler_protection is set to true, in which case passages are withheld and the result says so. Finished books are searched in full. Set spoiler_protection to false to search the whole book. Examples: - {"query": "marriage", "book_id": "<book id>"} - {"query": "the hunt", "poem_id": "whoso-list-to-hunt"}

Searches the ReadingRate book catalog by title, author, genre, theme or difficulty, and shows the results as book cards. Each result carries a difficulty score from 0 to 100, built from nine scored dimensions of how hard the prose and the meaning are. Use when the user asks to find books by an author, on a subject, in a genre, or within a difficulty range. For one book's full analysis, use get_book_details. For prize winners, use get_award_winners. For many titles at once, such as a pasted list or a photographed shelf, use lookup_books_batch. Results do not say whether the user has read a book; get_reading_history does. Returns: title, authors, publication year, difficulty score, literary regard score, genres, description, awards, cover image. Examples: - {"query": "Toni Morrison"} - {"genres": ["Literary Fiction"], "difficulty_max": 50} - {"query": "war", "genres": ["Historical Fiction"], "difficulty_min": 40, "difficulty_max": 70} - {"query": "Преступление и наказание", "locale": "ru"}: answer in Russian using title_localized and description_localized. Difficulty scores do not depend on language.

Searches the words of every poem in the ReadingRate collection and returns the matching lines, the lines around each, and each poem's anchor, which get_poem, save_poem_line and annotate_poem_line accept. Use when the user half-remembers a line, or wants poems that mention an image or a subject, such as "the poem about the shattered statue in the desert". It returns only poems already in the collection; it does not write, continue or translate poems. It matches words, so a remembered phrase works better than a paraphrase. The poems are in English: for a reader writing in another language, search with the English words a poem would use, explain in the reader's language, and quote the poem's lines in the original English rather than in a translation of your own. Example: {"query": "the woods are lovely dark and deep"}

Builds a summary of the reader's reading between two dates, up to a year apart: books finished, time and pages read, the difficulty of what they read and highlights. ReadingRate computes it from the reader's records and saves it in their account, where it replaces any summary saved earlier for the same dates. Use when the reader asks for a review of a period that is not one calendar month, such as a year in review or a season. For a single calendar month, use get_monthly_reading_summary. Example: {"start_date": "2025-01-01", "end_date": "2025-12-31", "period_label": "2025"}

Moves a book that is already in the reader's ReadingRate library to another status: "reading" (sets the start date if there is none), "read" (sets the finish date, with an optional rating), "stopped", or "want_to_read" (clears the finish date). It replaces the book's current status, and for "read" its rating and finish date. 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": "<book id>", "status": "reading"} - {"book_id": "<book id>", "status": "read", "rating": 5}