add_terms
ChatGPTAdd 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. A term may optionally carry image_url — a public https link to a JPEG, PNG or WebP picture illustrating it; the server downloads and stores a copy. Recommended picture format: aspect ratio 7:4, ideally 1344×768, with the main subject in the centre (phones crop the frame to 4:3). At most 20 pictures per call: with more, split the terms into several calls. Terms without pictures have no such limit. A picture that fails is listed in image_errors with the term_id of the already saved term; it can be retried with update_terms for that term_id (calling add_terms again would add the term twice). 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": "приоритет"}]}. Pictures from this chat (generated or uploaded) go in images, with image_term_indexes listing the position in terms for each of them, e.g. images: [file1, file2], image_term_indexes: [0, 3]; they count towards the same 20 pictures per call.
change_terms_status
ChatGPTChange 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"}.
create_collection
ChatGPTCreate 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"}.
delete_collection
ChatGPTPermanently 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_terms
ChatGPTDelete 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"]}.
fetch
ChatGPTFetch the full content of a search result by its id (format 'collection:<id>'): collection details and all its terms with meanings, learning statuses and picture links. Example: {"id": "collection:874445486856081408"}.
get_languages
ChatGPTList languages supported by WordByWord with their short codes. Use these codes in create_collection and add_terms. Example: no arguments.
get_learning_stats
ChatGPTGet 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_vocabulary
ChatGPTGet the user's vocabulary terms grouped by collection: term, meaning, example, picture (image_url, null if none) and learning status. 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. Pass collection_id to fetch a single collection, omit it for the whole vocabulary. Example: {"collection_id": "874445486856081408"} or {} for everything.
list_collections
ChatGPTList 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.
request_feature
ChatGPTReport a missing capability to the WordByWord team. Call this when the user asks for something that cannot be done with the available tools (missing tool, missing field, unsupported action). Tell the user you are sending the request. Call at most once per conversation for the same request. Example: {"summary": "Export vocabulary to Anki", "missing_capability": "no export tool"}.
search
ChatGPTSearch the user's vocabulary collections by collection name, term or meaning. Returns matching collections; use fetch to load the full content of a result. Example: {"query": "Vorfahrt"}.
update_terms
ChatGPTEdit existing terms: fix the word, its translation, the example sentence or the picture. Only the fields you pass are changed, omitted fields stay as they are; an empty string clears the example or the picture. image_url is a public https link to a JPEG, PNG or WebP picture — the server stores a copy; at most 20 pictures per call. Recommended picture format: aspect ratio 7:4, ideally 1344×768, with the main subject in the centre (phones crop the frame to 4:3). 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."}]}. A picture from this chat (generated or uploaded) goes in image; then terms must contain exactly the one term it belongs to.
add_terms
Claudechange_terms_status
Claudecreate_collection
Claudedelete_collection
Claudedelete_terms
Claudefetch
Claudeget_languages
Claudeget_learning_stats
Claudeget_vocabulary
Claudelist_collections
Clauderequest_feature
Claudesearch
Claudeupdate_terms
Claude
