Kuliko AI

Delete a subject; cascade requires fresh interactive user confirmation. Use when the user wants to remove a subject and its saved content. Cascade reads the current path and subtree statistics and presents them in a confirmation form. Clients without form support must finish deletion in Kuliko; user_confirmed_cascade cannot bypass this requirement. Never retry a 409 automatically with cascade. Refresh the library after success.

delete_subject

Widget callback: complete an attempt and return scored results. This callback is called by the quiz widget after the user clicks Submit. Completing an attempt is irreversible. The widget waits for this call to return and then renders the score and per-question breakdown immediately, with analysis when available inline — do not re-render the results as chat text. If the user later asks for their results separately, use `get_quiz_results` instead.

finish_quiz

Generate an optional visual study aid for one saved flashcard, on request. Use when the user requests a visual aid for a saved card. This consumes Kuliko's image allowance and runs in the background. Resolve the card with list_learning_resources first. Existing images are reused, never replaced. Poll get_job_status every three seconds for a returned job_id; after completion, use get_flashcard_image to retrieve the private image or review_flashcards to display it. Do not automatically retry an uncertain submission. This does not create cards or change their review schedule.

generate_flashcard_image

Turn an existing study document into AI-generated learning resources. Use when the user asks to make flashcards for active recall or memorization, Cornell notes, summaries, a mind map, practice questions, or an exam-prep quiz from uploaded course notes, lecture notes, a PDF, or another existing document. Generation that finishes within a few seconds returns created IDs and a Kuliko consume link. Longer generation, and every quiz, returns a durable `job_id`; poll `get_job_status` until completion. Generated content is not echoed. If the user explicitly asks to see it in chat, retrieve it with `list_learning_resources` after generation completes. Do not use this when the caller already has complete structured resource content; use `save_flashcards`, `save_notes`, or `save_summaries`. Generated summaries include 3–5 nonblank conceptual pre_questions, answerable from the source and in the requested summary language. Show these ordered reflection prompts under “Before you read…” above the overview; they are not scored quizzes. Older saved summaries may omit them or contain []. Constraints: - For flashcards, notes, summaries, and mind_maps: the backend rejects new generation if that resource type already exists for the source, regardless of language. When language is omitted, Connect returns existing resources without generating new ones; their stored language is preserved. Specifying language does not allow regeneration. Existing resources are never overwritten. - For quizzes: cannot generate a new quiz if the source has an incomplete quiz, including one never attempted. Complete existing quizzes first. After enqueueing, poll the returned job instead of calling generation again.

generate_learning_resources

Generate and save a cited study guide on a chosen topic using Kuliko AI. Use when the user wants a study guide without uploading files or having an existing library. Resolve an existing subject with list_subjects, or create one with create_subject, then pass its subject_id. This submits immediately and uses the document generation allowance. Optional guidance specifies the audience, level, or focus; do not draft the document in chat first. Omitted or empty generate_resources creates only the guide. Include flashcards, notes, or summaries only when requested for practice or review. For quizzes, wait for completion and use generate_learning_resources on the saved source. Omit display_name to use the topic with backend title deduplication. Returns a job_id: poll get_job_status until completion or failure. Never automatically resubmit after an uncertain response or terminal failure. Use open_study_guide_generator instead when it is available and the user wants to configure a widget. Otherwise use this direct tool.

generate_study_guide

Get metadata for one document, not its extracted body text. Use when the user asks about a stored file's title, size, tags, processing metadata, or timestamps. Returns those fields without the body text. Use `get_document_text` only when the full extracted text is actually needed. `mastery_level` is quiz performance, not overall readiness. When a quiz rating is unavailable it returns "Not quiz verified" instead of a level.

get_document

Get the full extracted text of one document. Preserve numbered citation links and Sources when retrieving AI-generated Markdown. Use only when the complete body of one source is required, such as before a full-content replacement with `update_document`. For ordinary study questions, prefer `search_documents` because a large PDF or set of lecture notes can fill the conversation context.

get_document_text

Get spaced-repetition flashcard due counts by subject. With subject_id, return one count including all descendant folders by default; scope="direct" counts only the selected folder. Without a subject, preserve the global per-direct-subject breakdown and source counts. Use when the user asks what is due today or how much review work remains, without opening a study session. To actually review due cards, use `review_flashcards`. To retrieve card records, use `list_learning_resources` with `resource_type="flashcards"`.

get_flashcard_due_counts

Retrieve a saved flashcard's temporary private image and preview URLs. Use for existing images or after generate_flashcard_image completes. URLs expire after expires_in seconds; call again to refresh. Never construct a public URL from a storage path. A missing image returns an error.

get_flashcard_image

Check the status of a queued Kuliko background job. Use after a tool returned a `job_id` — `generate_learning_resources`, `generate_study_guide`, `submit_study_document_generation`, `generate_flashcard_image`, or an upload — to tell the user whether the background work finished. Poll sparingly (every few seconds at most), and stop on a terminal status. Statuses: `queued` and `running` are in progress; `retrying` means a failed attempt will run again automatically; `completed` and `failed` are terminal. Treat any other status as terminal too. Once `completed`, generated resources are available via `list_learning_resources` and processed documents via `list_documents`.

get_job_status

Get the raw hierarchical mind-map tree for analysis or editing. Use when the model needs a saved study mind map's labels, descriptions, branches, or relationships as data for analysis or editing. This does not open the interactive graph; use `view_mind_map` when the user wants to see or explore the map visually.

get_mind_map_data

Get raw question and choice data for one quiz without starting it. Use when the model needs saved practice questions and choices for inspection or reporting without changing quiz progress. To let the user take or resume the quiz interactively, use `take_quiz` instead.

get_quiz_questions

Get report data for the latest completed attempt of one quiz. Use when the user asks how they did on a completed quiz or which topics to review for an exam. Returns score, per-question answers, performance analysis, strong areas, and areas to review when available. Analysis may be pending or failed; the persisted overall_score (percentage, including zero) and answers remain usable. Do not describe pending or failed analysis as ready. Completed answers may include explanations of why the correct answer is correct; legacy answers may omit them. Never invent missing explanations. Use `take_quiz` only for the interactive player.

get_quiz_results

Check whether a quiz is new, in progress, or completed. Use when the user asks whether a practice quiz is new, unfinished, or done. This reports state only. Use `take_quiz` when the user wants to open, resume, or view the quiz interactively.

get_quiz_status

Get one share group, including its members. Use when the user wants to inspect one group's name and current members. Member objects include `member_user_id`, which is required when removing a member from the group.

get_share_group

Widget callback: open the selected document's original file with a temporary private URL. Use after the learner opens a saved document; access is checked for the current account and unsupported or unavailable originals produce an explicit error.

get_study_document_preview

Widget callback: read the selected saved item using its library kind and ID. Authentication remains scoped to the current learner; missing or inaccessible items return a service error.

get_study_item

Widget callback: read backend activity statistics and flashcards due for the current learner. Missing practice evidence remains missing; this callback does not manufacture readiness scores or save practice.

get_study_progress

Get a subject by stable ID with root-first ancestor breadcrumb and subtree_stats. Use subtree_stats for study/readiness across this subject and descendants. Top-level statistics describe direct membership only. Names may repeat in other folders; retain the ID and breadcrumb. Read this before deleting to explain affected content and child_count to the user.

get_subject

Read the saved subject mind map synthesized from descendant source maps. Use when inspecting a subject-wide synthesis and whether it needs refresh. The returned state is authoritative: out_of_sync means subtree changes have made the saved synthesis stale. This read does not regenerate it. Keep each node's source_id and the map's subject_id unchanged.

get_subject_mind_map

Get the user's plan, subscription status, and remaining document allowance. Use when the user asks which plan they have, whether Kuliko Pro is active, or why an upload quota or file-type limit may apply. Also use once before generating a study guide with `generate_study_guide`: `documents.remaining` is how many more documents Kuliko can store right now (`documents.unlimited` on Pro). If it is 0, tell the user before submitting generation; `documents.reset_at` says when it reopens, if known. This is read-only and does not return upgrade links or purchase instructions.

get_subscription

Widget callback: import an explicitly confirmed file with the learner's selected metadata. Omit lang to follow the source document language. Empty resource selection stores only the document. This callback does not alter the legacy upload tool.

import_study_document

Use to open Kuliko Library for browsing saved subjects, documents, and learning resources. Takes no arguments; opening the library does not create material or start practice. The learner chooses the next activity.

open_kuliko_library

List saved document tags, including descendant folders for subject study. Use scope="direct" to show only tags on documents in the selected folder.

list_document_tags

List stored study documents, optionally filtered by subject or title. Use when the user wants to browse their PDFs, course notes, lecture notes, or other source material, or when another tool needs a document ID. This does not search inside content; use `search_documents` for relevant passages. `mastery_level` is quiz performance, not overall readiness. When a quiz rating is unavailable it returns "Not quiz verified" instead of a level.

list_documents

List stored HTML artifact metadata without returning full HTML bodies. Use this to discover artifact IDs, titles, descriptions, tags, and document associations before updating or deleting an artifact. Results can be restricted to one subject or source/document.

list_html_artifacts

List saved resource tags, including descendant folders for subject study. Use scope="direct" to show only tags on resources in the selected folder.

list_learning_resource_tags

List or search saved flashcards, notes, summaries, mind maps, or quizzes. Use when the user or model needs existing learning resources as raw data, such as finding a quiz ID, reading saved summaries, or inspecting authored flashcards. This never creates resources and never launches an interactive study experience. To create new resources from a document with Kuliko AI, use `generate_learning_resources`. To persist structured content already authored by the model, use the corresponding `save_*` tool. To study interactively, use `review_flashcards`, `take_quiz`, or `view_mind_map`.

list_learning_resources

List documents the current user has shared. Use when the user wants to see who they shared study documents with or whether recipients accepted them. Status meanings: `pending` means the recipient has not responded; `accepted` includes `copied_source_id`; `declined`, `revoked`, and `expired` are terminal states; `failed` includes an `error` describing why the accept-copy job failed.

list_outgoing_shares

List the user's quiz-attempt history with scores and completion status. Use when the user wants a cross-quiz progress report, recent exam-practice history, or IDs and statuses for previous attempts. This does not open a quiz.

list_quiz_attempts

List reusable document share groups owned by the current user. Use when the user wants to browse their saved recipient groups or find a group ID before sharing a document or changing group membership.

list_share_groups

List study subjects or courses with document counts and due-work status. Use when the user wants to browse their Kuliko library by course or topic, find a subject ID for another tool, or see which subjects have study work due. `only_due=true` restricts the list to subjects with review work due; for exact spaced-repetition flashcard counts use `get_flashcard_due_counts`. The default is a flat list. Use root_only=true for roots or parent_subject_id for immediate children. Names may repeat across folders: use IDs and get_subject breadcrumbs to disambiguate. Top-level counts and only_due are DIRECT membership; use subtree_stats for subject-wide study/readiness. Never sum overlapping parent and descendant subtree totals. Resources retain only their direct subject_id; do not add ancestor memberships. `mastery_level` is quiz performance, not overall readiness. When a quiz rating is unavailable it returns "Not quiz verified" instead of a level.

list_subjects

Move a subject and its descendants under a parent ID, or null to move to root. The parent field is required. Use IDs, never infer a parent from its name. Resources keep their direct subject IDs. Moves cannot form cycles, exceed 32 levels, or collide with a sibling name. Refresh subject paths and study context after success; existing subject mind maps may now be stale.

move_subject

Open a widget where the user chooses a subject and generates a cited study guide. Use when the user wants a saved guide from a topic without uploading a file. This opens a form only: it does not generate, save, or consume generation quota. Supplied fields prefill editable controls. The user starts generation with the widget's Generate study guide button. Omitted/empty resources means document only. Omit display_name to use the topic with backend deduplication. Use generate_study_guide to submit directly from the conversation. Pass an existing job_id to resume its progress instead of starting another submission. After submission, the shared creation card tracks the job and links to the saved material in Kuliko.

open_study_guide_generator

Use to preview a host-owned PDF, text, Markdown, PNG, or JPEG file in Kuliko. Preview alone does not save or upload the file. Import requires the learner to choose a destination subject and explicitly confirm in the app.

open_kuliko_file

Widget callback: submit one spaced-repetition flashcard rating. This callback is called by the flashcard widget after the user picks Again, Hard, Good, or Easy. The rating replaces the card's current review schedule. Do not call it to start or continue a model-driven review; use `review_flashcards` to open the interactive session instead.

rate_flashcard

Widget callback: read the account's current study-guide generation allowance before showing the creation form. Returns document and total-document daily and monthly remaining allowances without creating material.

read_study_generation_quota

Widget callback: read supported study preferences together with their native settings schema. Opening settings does not persist defaults or change any current learner preferences.

read_study_settings

Widget callback: read persisted results while analysis is pending. Only reads the attempt; never completes it or queues analysis. The widget bounds refreshes and stops on ready, failed, inactivity, or disposal.

refresh_quiz_results

Remove one tag from an existing resource without deleting the resource. Preserves its content and other tags. Use list_learning_resources to find the resource ID, current subject, and exact tag text. Supports flashcards, notes, summaries, quizzes, and mind maps, but not HTML artifacts or documents. Returns the updated resource.

remove_learning_resource_tag