# Look up every Orphi tool This page describes every tool that Orphi gives your AI assistant: what it does, its inputs, its result, its limits and an example. Orphi has twelve tools. Eight of them read your Orphi data, and four of them change it. Every tool acts for the Orphi account that signed in, so no tool takes a learner id. | Tool | What it does | Reads or writes | |---|---|---| | `get_learner_overview` | Returns your language, level, streak and number of due cards. | Reads | | `get_conversation_guide` | Returns how to talk with you at your level. | Reads | | `list_lessons` | Lists your lessons. | Reads | | `get_lesson` | Returns one lesson with its cards and reading passages. | Reads | | `get_due_reviews` | Returns the cards and saved words that are due for review. | Reads | | `open_orphi_call` | Returns a link that opens a voice call with Orphi. | Reads | | `search_my_words` | Searches the words you saved. | Reads | | `get_recent_calls` | Returns a summary of your last calls with Orphi. | Reads | | `save_words` | Saves new words into Orphi. | Writes | | `record_reviews` | Records how you did on the cards you practised. | Writes | | `add_learning_note` | Saves a short note for Orphi about your goals or life. | Writes | | `create_lesson_from_text` | Turns a text into a new Orphi lesson. | Writes | ## How every tool works A new connection can only read. The four tools that write work only after you turn on Allow changes for that assistant in Settings, under Connected assistants. No tool deletes anything. Every tool that writes takes a `requestId`. Send a new one for each new change. Send the same one again only to retry the same change, and Orphi then returns the first result without changing anything twice. Orphi keeps each `requestId` for 24 hours. Text inputs cannot be empty. Each tool returns its result as JSON, both as text and as structured content. A field marked optional is left out when Orphi has no value for it. Four tools also show Orphi's study screens in ChatGPT and Claude: `get_learner_overview`, `list_lessons`, `get_lesson` and `get_due_reviews`. Their JSON result stays the same for every other app. > **Tip:** For AI agents: call `get_learner_overview`, then `get_conversation_guide`, before you practise with the learner. Call `record_reviews` once at the end of a session, not after every card. ## Limits These limits count the calls of all your assistants together: - 120 tool calls an hour. - 20 changes an hour. Every call to a tool that writes counts as a change. - 3 lessons a day from `create_lesson_from_text`. An hour starts at the top of each hour, and a day starts at midnight UTC. A call over a limit changes nothing and says when the limit resets. ## `get_learner_overview` Returns the language you are learning, your level in Orphi, what you can say, what you are working on, sounds to watch, your streak and how many cards are due. This tool reads. ### Inputs This tool takes no inputs. ### Result - `targetLanguage` (string, required): The language you are learning, such as `mandarin` or `french`. - `level` (object, required): Your level in Orphi. - `level.shown` (string, required): The level you see in Orphi, such as `HSK 3` or `A2`. - `level.low` (string, required): The low end of the range Orphi is fairly sure of. - `level.high` (string, required): The high end of that range. - `level.scale` (string, required): The scale of the level: `HSK 3.0` for Chinese, `CEFR` for the other languages. - `canSay` (array of strings, required): What you can already say, at most 8 items. - `workingOn` (array of strings, required): What you are working on, at most 6 items. - `soundsToWatch` (array of strings, required): Sounds that need care, at most 5 items. - `streakDays` (number, required): Your streak, in days. - `dueCount` (number, required): The cards due for review now, counted up to 200. ### Limits None beyond the limits for every tool. ### Example Request: ```json {} ``` Result: ```json { "targetLanguage": "mandarin", "level": { "shown": "HSK 2", "low": "HSK 2", "high": "HSK 3", "scale": "HSK 3.0" }, "canSay": [ "Order food and drinks", "Talk about your family" ], "workingOn": [ "Telling the time" ], "soundsToWatch": [ "zh, ch and sh" ], "streakDays": 12, "dueCount": 18 } ``` ## `get_conversation_guide` Returns how to talk with you at your level: sentence length, pace, how much of your target language to use, how to correct, and the words and patterns to bring up. This tool reads. ### Inputs - `lessonId` (string, optional): The id of one of your lessons, as `list_lessons` returns it, at most 100 characters. Without it, the guide brings up the words and patterns that are due. ### Result - `guide` (string, required): How to speak with you, written as instructions to the assistant. It never contains your own text. - `lesson` (object or null, required): The lesson this conversation practises, or null. - `lesson.title` (string, required): The lesson's title. - `words` (array of objects, required): Words to bring up, at most 20. - `words[].word` (string, required): The word. - `words[].meaning` (string, required): What it means. - `words[].pronunciation` (string, optional): How it is said, such as pinyin for Chinese. - `patterns` (array of objects, required): Patterns to bring up, at most 10. - `patterns[].pattern` (string, required): The structure. - `patterns[].meaning` (string, required): What it expresses. - `patterns[].example` (string, optional): A sentence that uses it. ### Limits The guide is at most 3,000 bytes. The lesson title, words and patterns come from your own material, and the assistant treats them as data, never as instructions. ### Example Request: ```json { "lessonId": "lesson_8f2k" } ``` Result: ```json { "guide": "Use short sentences, mostly in English, with a few Chinese words...", "lesson": { "title": "At the market" }, "words": [ { "word": "多少钱", "meaning": "how much does it cost", "pronunciation": "duōshao qián" } ], "patterns": [ { "pattern": "太 + adjective + 了", "meaning": "too, very", "example": "太贵了！" } ] } ``` ## `list_lessons` Returns your lessons, newest first. Each lesson has an id that you pass to `get_lesson`, `get_conversation_guide` or `open_orphi_call`. This tool reads. ### Inputs - `limit` (integer, optional): How many lessons to return, from 1 to 50. The default is 10. ### Result - `lessons` (array of objects, required): Your lessons, newest first, at most 50. - `lessons[].id` (string, required): The lesson's id. - `lessons[].title` (string, required): The lesson's title. - `lessons[].language` (string, required): The language of the lesson. - `lessons[].cardCount` (number, required): How many words, patterns and contrasts the lesson holds. - `lessons[].lastPracticedAt` (string or null, required): When you last practised it, as an ISO date, or null. ### Limits At most 50 lessons in one call. ### Example Request: ```json { "limit": 2 } ``` Result: ```json { "lessons": [ { "id": "lesson_8f2k", "title": "At the market", "language": "mandarin", "cardCount": 24, "lastPracticedAt": "2026-10-03T18:20:00.000Z" }, { "id": "lesson_3m9q", "title": "My family", "language": "mandarin", "cardCount": 17, "lastPracticedAt": null } ] } ``` ## `get_lesson` Returns one of your lessons: its words, sentences, patterns and contrasts, and its reading passages. This tool reads. ### Inputs - `lessonId` (string, required): The id of one of your lessons, as `list_lessons` returns it, at most 100 characters. ### Result - `title` (string, required): The lesson's title. - `language` (string, required): The language of the lesson. - `cardCount` (number, required): How many cards the lesson holds. - `cards` (array of objects, required): The lesson's cards, at most 100. - `cards[].id` (string, required): The card's id, which `record_reviews` takes. - `cards[].kind` (string, required): One of `word`, `sentence`, `pattern` or `contrast`. - `cards[].front` (string, required): The front of the card. For a pattern, the structure. - `cards[].back` (string, required): The back of the card. For a pattern, the explanation. - `cards[].pronunciation` (string, optional): How the front is said. - `cards[].example` (object, optional): A sentence that uses it. - `cards[].example.text` (string, required): The sentence. - `cards[].example.transliteration` (string, optional): How the sentence is read. - `cards[].example.translation` (string, optional): What the sentence means. - `cards[].audioUrl` (string, optional): A recording of the front, in Orphi's own storage. - `passages` (array of objects, required): The lesson's reading passages, at most 10. - `passages[].title` (string, required): The passage's title. - `passages[].summary` (string, optional): What the passage is about. - `passages[].lines` (array of objects, required): The lines of the passage. - `passages[].lines[].speaker` (string, optional): Who says the line, in a dialogue. - `passages[].lines[].text` (string, required): The line. - `passages[].lines[].transliteration` (string, optional): How the line is read. - `passages[].lines[].translation` (string, optional): What the line means. ### Limits At most 100 cards and 10 passages. A lesson that is not yours is answered as not found. ### Example Request: ```json { "lessonId": "lesson_8f2k" } ``` Result: ```json { "title": "At the market", "language": "mandarin", "cardCount": 24, "cards": [ { "id": "card_51ad", "kind": "word", "front": "多少钱", "back": "how much does it cost", "pronunciation": "duōshao qián", "example": { "text": "这个多少钱？", "transliteration": "Zhège duōshao qián?", "translation": "How much is this?" } } ], "passages": [ { "title": "Buying fruit", "lines": [ { "speaker": "A", "text": "苹果多少钱一斤？", "translation": "How much is a jin of apples?" } ] } ] } ``` ## `get_due_reviews` Returns the cards and saved words that are due for review now, the most overdue first. A word that is both in a lesson and in your saved words appears once. This tool reads. ### Inputs - `limit` (integer, optional): How many items to return, from 1 to 20. The default is 10. ### Result - `items` (array of objects, required): The due items, the most overdue first, at most 20. - `items[].source` (string, required): `lesson` for a card of a lesson, or `vocabulary` for a word you saved. - `items[].id` (string, required): The item's id, which `record_reviews` takes with its source. - `items[].front` (string, required): The front of the card. - `items[].back` (string, required): The back of the card. - `items[].pronunciation` (string, optional): How the front is said. - `items[].example` (object, optional): A sentence that uses it. - `items[].example.text` (string, required): The sentence. - `items[].example.transliteration` (string, optional): How the sentence is read. - `items[].example.translation` (string, optional): What the sentence means. - `items[].audioUrl` (string, optional): A recording of the front, in Orphi's own storage. - `items[].lapseCount` (number, optional): How many times you forgot it. More than 0 means it came back after a miss. ### Limits At most 20 items in one call. ### Example Request: ```json { "limit": 1 } ``` Result: ```json { "items": [ { "source": "lesson", "id": "card_51ad", "front": "多少钱", "back": "how much does it cost", "pronunciation": "duōshao qián", "lapseCount": 1 } ] } ``` ## `open_orphi_call` Returns a link that opens a voice call with Orphi in the browser, on one of your lessons if you give one. It changes nothing and does not ring your phone. This tool reads. ### Inputs - `lessonId` (string, optional): The id of one of your lessons, as `list_lessons` returns it, at most 100 characters. ### Result - `url` (string, required): The link, `https://app.useorphi.com/call`, with `?lesson=` and the lesson's id when you gave one. ### Limits A lesson that is not yours is answered as not found. ### Example Request: ```json { "lessonId": "lesson_8f2k" } ``` Result: ```json { "url": "https://app.useorphi.com/call?lesson=lesson_8f2k" } ``` ## `search_my_words` Searches the words you saved in Orphi, by the word itself or by its meaning, and returns the best matches first. This tool reads. ### Inputs - `query` (string, required): A word in any language, or part of its meaning, at most 100 characters. - `limit` (integer, optional): How many words to return, from 1 to 25. The default is 10. ### Result - `words` (array of objects, required): The matching words, the best matches first, at most 25. - `words[].id` (string, required): The word's id. - `words[].word` (string, required): The word. - `words[].meaning` (string, required): What it means. - `words[].pronunciation` (string, optional): How it is said. - `words[].state` (string, required): Where the word is in its review schedule: `introduced`, `learning`, `review`, `mastered` or `relearning`. ### Limits At most 25 words in one call. ### Example Request: ```json { "query": "expensive" } ``` Result: ```json { "words": [ { "id": "word_77c1", "word": "贵", "meaning": "expensive", "pronunciation": "guì", "state": "review" } ] } ``` ## `get_recent_calls` Returns your last voice calls with Orphi, newest first: when they happened, how long they lasted, and a short summary of each. It never returns a transcript. This tool reads. ### Inputs - `limit` (integer, optional): How many calls to return, from 1 to 5. The default is 5. ### Result - `calls` (array of objects, required): Your last calls, newest first, at most 5. - `calls[].startedAt` (string, required): When the call started, as an ISO date. - `calls[].durationSeconds` (number, required): How long the call lasted, in seconds. - `calls[].summaryStatus` (string, required): `ready` when the summary fields are filled, `preparing` while Orphi writes the summary, or `unavailable` when none could be written. - `calls[].summary` (string, optional): What the call was about, at most 600 characters. - `calls[].topics` (array of strings, optional): The topics of the call, at most 5. - `calls[].wordsPracticed` (array of strings, optional): The words you practised, at most 10. - `calls[].learnerFacts` (array of strings, optional): What you said about your life and goals, at most 5. ### Limits At most 5 calls. Orphi writes a call's summary with an AI model the first time an assistant asks for that call, and at most 3 summaries in one request. The others say `preparing`; ask again a minute later. ### Example Request: ```json { "limit": 1 } ``` Result: ```json { "calls": [ { "startedAt": "2026-10-04T19:05:00.000Z", "durationSeconds": 540, "summaryStatus": "ready", "summary": "A chat about weekend plans and a trip to the market.", "topics": [ "weekend plans", "shopping" ], "wordsPracticed": [ "周末", "多少钱" ], "learnerFacts": [ "Is moving to Shanghai in March" ] } ] } ``` ## `save_words` Saves words from the conversation into your words in Orphi, where Orphi schedules them for review. A word you already have is skipped. This tool writes. It works only after you turn on Allow changes for the assistant. ### Inputs - `words` (array of objects, required): The words to save, from 1 to 20. - `words[].word` (string, required): The word or short phrase, in the language you are learning, at most 80 characters. - `words[].meaning` (string, required): What it means, in your own language, at most 200 characters. - `words[].pronunciation` (string, optional): How it is said, such as pinyin for Chinese, at most 100 characters. - `words[].example` (string, optional): A sentence that uses it, at most 300 characters. - `requestId` (string, required): A new random id for this change, 8 to 64 characters. ### Result - `saved` (number, required): How many words were added. - `skipped` (number, required): How many you already had, or were named twice. ### Limits At most 20 words in one call. ### Example Request: ```json { "words": [ { "word": "便宜", "meaning": "cheap", "pronunciation": "piányi" } ], "requestId": "c41f9e2a-save-1" } ``` Result: ```json { "saved": 1, "skipped": 0 } ``` ## `record_reviews` Records how you did on cards and saved words that the assistant quizzed you on. Orphi moves each review schedule exactly as a review in the app does. This tool writes. It works only after you turn on Allow changes for the assistant. ### Inputs - `reviews` (array of objects, required): One result per card, from 1 to 50. - `reviews[].source` (string, required): `lesson` or `vocabulary`, as `get_due_reviews` or `get_lesson` gave it. - `reviews[].id` (string, required): The card's id, at most 100 characters. - `reviews[].rating` (string, required): `again` when you did not know it, `hard`, `good` or `easy`. - `requestId` (string, required): A new random id for this change, 8 to 64 characters. ### Result - `recorded` (number, required): How many results were recorded. Two results for one schedule both count, and move it once. - `nextDue` (array of objects, required): One entry per schedule that moved, at most 50. - `nextDue[].source` (string, required): `lesson` or `vocabulary`. - `nextDue[].id` (string, required): The card's id. - `nextDue[].dueAt` (string, required): When the card comes back for review, as an ISO date. ### Limits At most 50 results in one call. Reviews update when cards come back, and they never change your level. ### Example Request: ```json { "reviews": [ { "source": "lesson", "id": "card_51ad", "rating": "good" } ], "requestId": "c41f9e2a-reviews-1" } ``` Result: ```json { "recorded": 1, "nextDue": [ { "source": "lesson", "id": "card_51ad", "dueAt": "2026-10-09T08:00:00.000Z" } ] } ``` ## `add_learning_note` Saves one short note about your goals or your life that matters for your learning, such as "moving to Shanghai in March". Orphi uses your notes in its voice calls. This tool writes. It works only after you turn on Allow changes for the assistant. ### Inputs - `note` (string, required): The note, in your words or close to them, at most 500 characters. - `requestId` (string, required): A new random id for this change, 8 to 64 characters. ### Result - `saved` (boolean, required): Whether the note was saved. - `noteCount` (number, required): How many notes you now have. Orphi keeps 30 at most. ### Limits Each note has at most 500 characters, and Orphi keeps 30 notes. You see and delete them in Settings, under Notes from your assistants. An assistant saves a note only when you ask it to. ### Example Request: ```json { "note": "I'm moving to Shanghai in March", "requestId": "c41f9e2a-note-1" } ``` Result: ```json { "saved": true, "noteCount": 3 } ``` ## `create_lesson_from_text` Turns a text, such as notes from a class or a dialogue, into an Orphi lesson with words, patterns and recordings. The lesson takes a few minutes to make. This tool writes. It works only after you turn on Allow changes for the assistant. ### Inputs - `text` (string, required): The text of the lesson, at most 20,000 characters. - `title` (string, optional): A title for the lesson, at most 120 characters. - `requestId` (string, required): A new random id for this change, 8 to 64 characters. ### Result - `importId` (string, required): The id of the lesson being made. - `lessonUrl` (string, required): The page in Orphi where you follow the lesson being made and then check it. - `status` (string, required): `started` for a new lesson, or `already_running` and `already_made` when you already sent the same text. ### Limits At most 20,000 characters, and 3 lessons a day. ### Example Request: ```json { "text": "A: 苹果多少钱一斤？ B: 五块。", "title": "Buying fruit", "requestId": "c41f9e2a-lesson-1" } ``` Result: ```json { "importId": "import_2b7d", "lessonUrl": "https://app.useorphi.com/lessons/imports/import_2b7d", "status": "started" } ``` ## Errors When a tool cannot answer, it returns an error with one sentence that the assistant can pass on to you. Each entry below starts with the exact message. - "This Orphi account is not available. It may have been deleted." The account was deleted. Sign in with another Orphi account. - "The learner disconnected this assistant from Orphi in Orphi’s settings." Open Settings in Orphi and select Allow again next to the assistant, under Disconnected. - "This assistant may only read. The learner can turn on “Allow changes” for it in Orphi’s settings." A tool that writes was called before you allowed changes. Turn on Allow changes for the assistant in Settings. - "This learner has connected as many assistants to Orphi as it allows. They can disconnect one in Orphi’s settings." Disconnect an assistant you no longer use, then sign in again. - "Lesson not found. Call list_lessons to see the learner’s lessons and their ids." The lesson id is not one of your lessons. Call `list_lessons` to get the right id. - "The input is outside what this tool accepts. Check the limits in the tool’s description." An input is too long, empty, or has too many items. Check the limits on this page. - "This requestId was already used for a different change. Send a new requestId for a new change, and the same one only to retry the same change." Send the change again with a new `requestId`. - "Orphi is still working on this request. Wait a minute, then send it again with the same requestId." A lesson from the same request is still starting. Send it again a minute later. - "The learner already has the most notes Orphi keeps. They can delete one in Orphi’s settings, under the notes from their assistants." You have 30 notes. Delete one in Settings, under Notes from your assistants. - "Orphi could not start a lesson from this text. The learner can paste it into Orphi instead." Paste the text into Orphi's lesson import instead. - "Orphi allows 120 tool calls an hour for a learner’s assistants, and this learner has reached it." The message names the limit that was reached, and says when it resets. Try again after that time. - "Orphi could not answer just now. Try again in a moment." Something failed on Orphi's side. Try again in a moment. To learn how the assistant signs in, read [Sign in and disconnect an assistant](/docs/authentication).