WordByWord – Learn Languages

Add new terms (words or phrases with their translations) to one of the user's collections. Typical use: saving the unfamiliar words of a text the user reads or translates in a language they are learning. Call this tool only after the user agrees. For each term pass the meaning in the user's language and an example sentence taken from the same text. Use list_collections to pick the collection first. Language codes are short codes like 'en', 'de', 'ru'. If the user has no suitable collection yet, call create_collection first, then use its returned collection_id here. Pass source_title (and source_url when the words come from a page) so the user later sees where each word came from. Returns the url of the collection — show it to the user so they can open it. Example: {"collection_id": "874445486856081408", "term_language_code": "de", "meaning_language_code": "ru", "terms": [{"term": "Vorfahrt", "meaning": "приоритет"}]}.

add_terms

Change the learning status of one or more terms at once, e.g. mark them as known. Learning statuses, from least to best known: new (added, not studied yet), recognize (recognised in context, first correct answers), familiar (recalled, but not reliably yet), learned (recalled reliably, shown for review less often), known (fully learned; only this status counts toward the collection's learned-words total). Terms move up and down automatically as the user trains; setting a status by hand overrides that. Example: {"collection_id": "874445486856081408", "term_ids": ["920000000000000001"], "status": "known"}.

change_terms_status

Create a new vocabulary collection for the language the user is learning. Use get_languages to find the language code. The new collection is private. Returns the collection id and its url — show the url to the user so they can open the collection. Example: {"name": "German basics", "language_code": "de"}.

create_collection

Permanently delete one of the user's collections with all its terms. Destructive and irreversible: always confirm with the user before calling this. Example: {"collection_id": "874445486856081408"}.

delete_collection

Delete terms from one of the user's collections by their ids (get them from get_vocabulary). Destructive: confirm with the user before calling this. Example: {"collection_id": "874445486856081408", "term_ids": ["920000000000000001"]}.

delete_terms

Edit existing terms: fix the word, its translation or the example sentence. Only the fields you pass are changed, omitted fields stay as they are; an empty string clears the example. Term ids come from get_vocabulary or add_terms. Either all terms are updated or none: an unknown or foreign id rejects the whole call. To change the learning status use change_terms_status instead. Example: {"terms": [{"term_id": "920000000000000001", "example": "Wir haben Vorfahrt."}]}.

update_terms

Fetch the full content of a search result by its id (format 'collection:<id>'): collection details and all its terms with meanings and learning statuses. Example: {"id": "collection:874445486856081408"}.

fetch

Get the user's learning statistics: current and longest daily streak, term counts and status distribution. Pass collection_id to scope to one collection. Example: {} for all collections or {"collection_id": "874445486856081408"}.

get_learning_stats

List languages supported by WordByWord with their short codes. Use these codes in create_collection and add_terms. Example: no arguments.

get_languages

List the user's vocabulary collections with term counts, learning progress and the url of each collection. Call this first to find the collection_id for other tools. Example: no arguments.

list_collections