Log a reading session
log_reading_sessionLogs 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": "", "pages_read": 30}
{"book_id": "", "current_page": 150}
{"book_id": "", "front_matter_ends_on": "lx", "roman_page": "liv"}
{"book_id": "", "notes": "The argument only lands once you have read the footnotes."}
{"book_id": "", "current_page": 212, "date": "yesterday"}
A day the reader forgot to log: send date ("yesterday", or "YYYY-MM-DD") when they say the reading was on an earlier day ("I forgot to log yesterday", "on Tuesday I read to page 212"). Any day from when they started the book up to today counts, never a future day. That day's entry is created, or extended if it has one; its pages run on from the last entry before it. The book's current page only moves forward: logging an older day never moves it back. "Today" and "yesterday" are the reader's own days, in the time zone their account keeps; send timezone (an IANA name such as "Europe/London") when you know it and the account may not.
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": {
"book_id": "<book_id>"
},
"name": "log_reading_session"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | The day the reading was done when it was not today: "yesterday" or "YYYY-MM-DD". Never a future day, nor one before the reader started the book. Default today | |
| notes | No | The reader's note on the day's reading, added to that day's journal entry | |
| book_id | Yes | The book's ReadingRate id or its library entry id | |
| timezone | No | The reader's IANA time zone, such as "Europe/London", for what today and yesterday mean. Default: the one their account keeps, else UTC | |
| pages_read | No | Pages read in this session, added to the current page | |
| roman_page | No | The page the reader is now on in the book's roman-numbered introduction or preface, such as "liv" | |
| current_page | No | The page the reader is now on, as printed in arabic numerals | |
| front_matter_ends_on | No | The last roman-numbered page of the reader's copy, such as "lx" (or 60); "0" when it has none or they skipped it |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| book | No | The book: id, slug, title, authors | |
| date | No | The day the reading was logged for (YYYY-MM-DD, the reader's date) | |
| message | Yes | Human-readable result | |
| success | Yes | Whether the session was logged | |
| estimate | No | hours_remaining and description; null when the total pages are unknown | |
| progress | No | current_page (the stored position, counted from page i when the copy has roman front matter), page_label (the page as the book prints it, e.g. "liv" or "10"), front_matter_pages, total_pages (printed pages of the reader's copy, without a roman introduction: show page_label of total_pages), percent_complete and pages_remaining (over the whole copy) | |
| velocity_used | No | Pages per hour used for the estimate | |
| status_changed | No | Set when the book moved from want-to-read to reading |