Tito

Stops a book import for good: no further chapters are imported and the import cannot be resumed — re-importing means preparing it again from the source. Chapters already saved stay (never deleted). Single-document imports are accepted within seconds and cannot be cancelled (import_not_cancellable) — the document can be deleted in the app. import_busy means the book is being advanced at this instant; try again in a moment.

cancel_import

Status of a cover preview: generating, ready (with url) or failed. The card polls this after preview_cover. Not for the model to call.

get_cover_preview

Creates a new private, free study space for the learner. productMode is the subject area that shapes the notes — general, healthcare, technology (coding / IT), stem (science & math) — only values listed in get_upload_context.productModes (defaultProductMode is what the app would preselect): infer it from the material or ask, and say which you chose. A cover picture is generated automatically from the name and description unless coverPrompt (a short description of the picture) or coverImage (a picture the user attached) is given. Use only when the user asks for a new space or none is suitable. Reports the plan's space limit if reached.

create_space

Reports an import's state: outcome (processing, materials_ready, saved_without_ai, partially_completed, failed, cancelled), stage (a book: mapping_chapters → importing_chapters → done), counts and per-part status, canRetry / canCancel, and a link to open it in Twinbook.

get_import_status

Returns the learner's plan, remaining monthly allowance (pages, uploads, AI credits), per-import limits (perImport.maxQuickPages: a PDF up to that many pages becomes one chapter; perImport.maxImportPages: longer documents up to that are processed as several chapters; perImport.maxBookPages with booksEnabled: longer documents import as books — chapter map first, then chapter by chapter, each chapter one upload; urlsEnabled / officeEnabled / youtubeEnabled: which link and file kinds this server accepts), the content kinds and note styles the app offers, and whether AI terms are accepted. Call before planning an import.

get_upload_context

Lists the learner's study spaces, most recently opened first, with canUpload (only spaces the learner created accept imports), chapter count, subject area and learning mode. Optional query filters by title. Use it to resolve a space the user NAMED to its id for prepare_import.destination; when no space was named, do not call it — prepare_import shows the card where the learner picks.

list_spaces

Stages and inspects ONE source — pasted text, a public URL, or an attached file — and returns a plan: real page count, how it will be processed (processing: quick = one chapter; chapters = Twinbook detects chapters itself; book = chapter map first, then chapter-by-chapter import, each chapter one upload — estimatedUsage.uploadsEstimated; save_only = stored without AI), estimated usage, warnings, blockedBy, a planId, and destinations (the learner's own spaces + whether a new one may be created). It shows the ONE card of this app: the learner taps a space to save into, or types a name (and picks a subject area) to create a new space and save in the same tap — the card performs the save itself. Pass destination.spaceId only when the user named the space (it is highlighted on the card). After this call say one short line and STOP; do not call commit_import yourself unless the user asks in chat. Provide exactly one of text, url, file. For links send the url itself (web page, PDF/Word/PowerPoint link, YouTube) — never download it yourself; a chat share link is refused, send that conversation as text.

prepare_import

Renders a cover picture for a space that does not exist yet, from a short prompt, in the app's own cover style. The Save-to-Twinbook card calls this itself when the learner creates a new space and on Refresh; it answers at once with status generating and the card polls get_cover_preview. One image generation per call, capped per import and per day (cover_limit_reached). Not for the model to call.

preview_cover

Resumes a paused book import (failed chapters are re-queued, finished chapters are kept) or re-submits a single upload that failed for a transient reason (canRetry true). Idempotent while the import is running. Returns import_not_retryable when nothing can be retried — then a fresh prepare_import is needed.

retry_import

Saves a prepared plan into a space. The Save-to-Twinbook card calls this itself when the learner taps; call it from chat only when the user explicitly asks ("yes, save it to Algebra 1"). Destination: spaceId (one of the learner's own spaces) or newSpace { title, productMode, cover } to create a space and save into it in one step; a plan prepared with a destination needs neither. Returns accepted within seconds; study materials generate in the background. A plan is imported at most once: calling again (same key, or any key for the same plan) returns the same import and never charges or creates twice. On a timeout, call again with the SAME key.

commit_import