Skip to main content
Glama

Log a reading session

log_reading_session
Destructive

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": "", "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

NameRequiredDescriptionDefault
dateNoThe 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
notesNoThe reader's note on the day's reading, added to that day's journal entry
book_idYesThe book's ReadingRate id or its library entry id
timezoneNoThe reader's IANA time zone, such as "Europe/London", for what today and yesterday mean. Default: the one their account keeps, else UTC
pages_readNoPages read in this session, added to the current page
roman_pageNoThe page the reader is now on in the book's roman-numbered introduction or preface, such as "liv"
current_pageNoThe page the reader is now on, as printed in arabic numerals
front_matter_ends_onNoThe 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

NameRequiredDescriptionDefault
bookNoThe book: id, slug, title, authors
dateNoThe day the reading was logged for (YYYY-MM-DD, the reader's date)
messageYesHuman-readable result
successYesWhether the session was logged
estimateNohours_remaining and description; null when the total pages are unknown
progressNocurrent_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_usedNoPages per hour used for the estimate
status_changedNoSet when the book moved from want-to-read to reading

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedInput schema / properties / date
      Added value: +{
      +  "description": "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",
      +  "type": "string"
      +}
    • changedInput schema / properties / notes / description
      Previous value: -"The reader's note on today's reading, added to today's journal entry"New value: +"The reader's note on the day's reading, added to that day's journal entry"
    • addedInput schema / properties / timezone
      Added value: +{
      +  "description": "The reader's IANA time zone, such as \"Europe/London\", for what today and yesterday mean. Default: the one their account keeps, else UTC",
      +  "type": "string"
      +}
    • addedOutput schema / properties / date
      Added value: +{
      +  "description": "The day the reading was logged for (YYYY-MM-DD, the reader's date)",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Goes well past the annotations by disclosing the merge rule (one journal entry per book per day; a second call extends pages and appends the note), the state transition from want-to-read to reading, the monotonic current-page rule, and that "0" for front_matter_ends_on removes previously counted pages. These are the concrete consequences behind idempotentHint=false and destructiveHint=true, which the annotations alone would not 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?

Well front-loaded with purpose, then usage, then parameter rules, then examples, then the date edge case. It is on the long side and a few clauses restate schema wording (the date-bounds rule appears in both prose and schema), so it is dense but not maximally tight.

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 an 8-parameter mutation with an output schema, the description covers the risky edge cases an agent would otherwise get wrong: backdated logging running on from an earlier entry, current page never moving backward, roman front-matter rollover, and caller time zone. Nothing material is left to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema coverage, the description adds real meaning: pages_read, current_page and roman_page are mutually exclusive ("only one of them; a note can be sent alone"), date is bounded to between book start and today, front_matter_ends_on is explained both as a carry-forward setting and as an undo via "0", and timezone is tied to what today/yesterday mean.

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?

Names a specific verb and resource and enumerates the concrete effects: sets the book's current page, adds pages to today's journal entry, appends the note. It also distinguishes itself from sibling mutations by naming add_book_to_library as the prerequisite for unknown books.

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?

Explicit trigger conditions are given ("Use when the user says how many pages they read, which page they are on, or wants a thought saved"), plus a hard exclusion ("For a book not yet in their library, use add_book_to_library first") and a retry guard ("do not repeat a call that succeeded").

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.