Books tools
Every tool in this module, with its full description, parameters, and return value. All of them require the module to be active first. See the Books overview for how to turn it on.
Core tools
Create, read, update, and delete entries. Every module has exactly these four.
books_add_entryAdd a book to the user's Books module. Requires the module to be active — see create_database.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| book | string | Yes | Title of the book (author may be included, e.g. 'Dune by Frank Herbert'). |
| status | want_to_read | reading | read | No | Reading status: 'want_to_read' (on the list, not started), 'reading' (in progress), or 'read' (finished). Defaults to unset if omitted. |
| rating | number | No | Rating on a 1-5 scale, typically given once the book is marked 'read'. |
| notes | string | No | Free-form notes about the book, e.g. thoughts, quotes, or reasons for reading it. |
| catalogId | string | No | Id of a book_catalog row from books_confirm_match, to attach structured metadata (author, ISBN, year, page count, cover). Optional: book (free text) is always fully sufficient on its own to log a book, with or without a catalog match. |
Returns
The created entry as JSON, including its id.
books_list_entriesList entries in the user's active Books module.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| limit | number | No | Max entries to return (default 100, max 500). |
Returns
Every entry in the active database, as a JSON array.
books_update_entryUpdate fields on an existing Books entry.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| entryId | string | Yes | ID of the Books entry to update. |
| book | string | No | Title of the book (author may be included, e.g. 'Dune by Frank Herbert'). |
| status | want_to_read | reading | read | No | Reading status: 'want_to_read' (on the list, not started), 'reading' (in progress), or 'read' (finished). |
| rating | number | No | Rating on a 1-5 scale, typically given once the book is marked 'read'. |
| notes | string | No | Free-form notes about the book, e.g. thoughts, quotes, or reasons for reading it. |
| catalogId | string | No | Id of a book_catalog row from books_confirm_match, to attach or replace structured metadata (author, ISBN, year, page count, cover). Optional: book (free text) is always fully sufficient on its own, and omitting this leaves the entry's existing catalog link unchanged. |
Returns
The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.
books_delete_entryDelete an entry from the user's active Books module.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| entryId | string | Yes | ID of the Books entry to delete. |
Returns
The updated or deleted entry as JSON. Returns an error if entryId does not belong to an entry in the active database.
Purpose-built tools
Shortcuts and queries shaped around how Books is actually used, so your agent doesn't have to fetch every entry and filter them itself.
books_attach_photoAttach a photo to an existing Books entry (replacing any photo already on it). If you have the image's raw bytes, pass photo_base64. If the user attached the image in a chat client (e.g. claude.ai), you cannot read its bytes: call this WITHOUT photo_base64 to get a one-time upload link, and give that link to the user so they can upload the photo themselves. The link expires in 30 minutes. Photos are stored privately; the returned viewPath is only viewable signed into the connacto web app as this user.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| entryId | string | Yes | ID of the Books entry to attach the photo to. |
| photo_base64 | string | No | The photo, base64-encoded (no data: URI prefix). Omit when you cannot read the image bytes — the tool then returns an upload link for the user instead. |
| photo_content_type | image/jpeg | image/png | image/webp | image/heic | No | MIME type of the photo, if photo_base64 is set. Defaults to image/jpeg. |
Returns
JSON with a private viewPath when photo_base64 was given, or an uploadUrl to hand the user when it was not.
books_list_currently_readingList entries in the user's active Books module that have status 'reading'.
Parameters
None. Call it with an empty object.
Returns
Matching entries as a JSON array.
books_reading_statsReturn counts of entries by status (want_to_read/reading/read) and the average rating across entries with status 'read' and a non-null rating, for the user's active Books module.
Parameters
None. Call it with an empty object.
Returns
Counts by status, total entry count, average rating for read books, and how many read books were rated, as JSON.
books_lookupSearch Open Library for candidate books matching a title (and optional author). Makes exactly one live network call and writes nothing. Each candidate is annotated cached:true/false based on whether it's already present in the shared book catalog (see books_confirm_match). Zero matches is not an error: the book can still be logged by title alone via books_add_entry without a catalogId. To attach a candidate's metadata to an entry, call books_confirm_match with the chosen candidate's fields to get a catalogId, then pass that to books_add_entry/books_update_entry.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| title | string | Yes | Book title to search for. |
| author | string | No | Author name, to narrow an ambiguous title search. |
| limit | number | No | Max candidates to return (default 5, max 10). |
Returns
Up to limit candidates, each with title, author, first publish year, ISBN, page count, cover URL, up to 10 subjects, edition count, and cached (whether it is already in the local catalog), as JSON.
books_confirm_matchCache one specific Open Library candidate (as returned by books_lookup) into the shared book catalog, then return its catalogId for use with books_add_entry/books_update_entry. Makes no network call: it upserts exactly the fields supplied, which should be copied verbatim from the chosen books_lookup candidate. This is a separate step from books_lookup, rather than auto-caching the top search hit, because the book catalog is shared across every user of connacto, not private per-user data. Free-text search over millions of works is routinely ambiguous (e.g. 'Dune' matches the novel, its sequels, and film tie-in editions), and auto-caching a guessed top hit risks a wrong match becoming permanent and visible to every future user who looks up that title. Re-fetching from Open Library here instead of trusting the supplied fields is also deliberately avoided: the values shown by books_lookup already are the confirmation, and a second fetch could silently return different data (e.g. a different edition's cover) than what was approved.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
| openLibraryId | string | Yes | Open Library work id from a books_lookup candidate, e.g. 'OL27482W' (the '/works/' prefix stripped). |
| title | string | Yes | Title, copied from the chosen books_lookup candidate. |
| author | string | No | Author, copied from the chosen books_lookup candidate. |
| isbn | string | No | A single representative ISBN, copied from the chosen books_lookup candidate. |
| firstPublishYear | number | No | First publish year, copied from the chosen books_lookup candidate. |
| pageCount | number | No | Page count, copied from the chosen books_lookup candidate. |
| coverUrl | string | No | Cover image URL, copied from the chosen books_lookup candidate. |
| subjects | string[] | No | Up to 10 subjects, copied from the chosen books_lookup candidate. |
Returns
The catalog row as JSON, including catalogId.