add_to_list
ChatGPTAdd catalog items to one of this person's existing custom lists — a collection they NAMED, like 'Halloween' or 'road trip'. The list can be given by id or by name. Adding something already on the list is a no-op, not an error — the response reports added and skipped separately, so report what actually happened rather than assuming every item landed. NOT for a generic "add to my playlist / watchlist / reading list" — that is the app's built-in save-for-later shelf, which is the 'watchlisted' reaction: use react_to_item.
clear_reaction
ChatGPTRemove this person's reaction to a catalog item entirely — and any 1-10 rating on it, since both are stored together. Use it when they ask to take something off their Watchlist, Read List or Playlist, or to undo a reaction they didn't mean. This is the ONLY way to un-save or un-react: never fake a removal by switching the reaction to 'meh' or 'skipped', which would record an opinion they don't hold. Returns previous — exactly what was removed — so it can be restored with react_to_item. cleared: false means there was no reaction on that item to remove.
create_list
ChatGPTCreate one of this person's custom lists, optionally seeded with items. Creating a list whose name they already have UPDATES that list instead of making a second copy, so re-running with the same name is safe. DO NOT use this to satisfy "add X to my playlist / watchlist / reading list". Those name the app's BUILT-IN save-for-later shelf, which is the 'watchlisted' reaction — call react_to_item instead. Creating a list called 'Playlist' alongside it leaves the person with two things of the same name and their save-for-later shelf untouched. Use this only for a genuinely separate, named collection the person asked for. If they do want one named after a medium's default shelf anyway, passing media_type and omitting name gives it the conventional name (Watchlist for film and TV, Read List for books, Playlist otherwise).
get_contribution_schema
ChatGPTWhat a catalog contribution needs before you can file one: required fields, the five taste axes and their poles, and which external id/link fields this media type accepts. Read this before suggest_new_items — the facet axes in particular are not guessable.
get_item_details
ChatGPTDISPLAY ITEMS TO THE PERSON. Results are rendered by the Interestnaut client as interactive cards — cover art, and one-tap buttons that record a reaction or save to their shelf. This is the tool that puts things in front of them; it returns the items' descriptive metadata at the same time. So whenever you have PICKED a set of things to show — a recommendation list, an answer to "what should I watch", a shortlist you just reasoned your way to — resolve each title with search_catalog and then call this ONCE with up to 20 ids. Writing the list out as prose instead leaves them with nothing to act on.
get_my_lists
ChatGPTRead this person's custom lists — the collections they curate by hand, as opposed to their reactions. Returns each list's id, name and size; pass include_items to also resolve the titles inside. Call this before add_to_list so you act on a list that actually exists.
get_my_ratings
ChatGPTRead only the items this person has scored 1-10, highest first. Ratings are sparse and deliberate, so they are the strongest available signal — a 9 means far more than a like.
get_my_reactions
ChatGPTRead this person's reaction history with their 1-10 ratings. This is the primary grounding for any recommendation — prefer it over inferring taste from a single mentioned title. By default this returns every opinion they have ever recorded, across all media, because good recommendations need the whole picture rather than a recent slice. Pulling the full set is the intended use; do not artificially narrow it to save room. 'skipped' is excluded by default and should usually stay excluded — it means they passed without engaging and carries no opinion, so it is noise for recommendation purposes.
get_queue
ChatGPTRead this person's Interestnaut listening queue: what's playing now, what's up next (who added each track and why), the station that keeps it topped up, and the last 15 tracks with how they ended (played / skipped / failed). Skips are taste signal — use them when choosing what to add.
get_taste_profile
ChatGPTThis person's taste profile, as Interestnaut describes it to them: archetype (plain name, display_name with its intensity modifier, a short blurb and an essence paragraph), five personality axes (0-100), loved/hated/ambivalent themes, the written summary, traits and tensions from their profile, top genres and decades, and a few representative titles. Derived from their whole reaction history — a cheap summary when you do not need item-level detail. Private to this person: speak to them about themselves, do not quote it as public.
list_archetypes
ChatGPTThe whole archetype system, not one person's result: the five axes with both poles described and their intensity modifier words, the rule that builds a display name, and all 32 archetypes with code, name, blurb, essence, the five pole letters spelled out, the five neighbouring codes, and the helmet art (a small looping WebP on our origin, its frame colour, and a one-line brief of what plays in the visor). Use this for any question about the archetypes as a set — what they are, what sits next to someone's, how one looks, or when asked to draw or describe them. Nothing here is personal; the person's own result comes from get_taste_profile.
queue_tracks
ChatGPTAdd songs to this person's listening queue by title and artist — up to 25 per call, resolved against the catalog in one batch (no need to search first; pass track_id when you already have it). Give each a short, specific reason they'll see on the track. play_next puts them right after the current song; otherwise they go at the end. Assistant additions stop at 20 tracks up next. The response separates queued, already-queued/unplayable, and not_in_catalog — report what actually happened.
rate_item
ChatGPTSet this person's 1-10 rating for an item. If they have no reaction on it yet, a 7 or above records a 'liked', 4-6 a 'meh', and below 4 a 'disliked' — an existing reaction is kept as-is. Use react_to_item when you want to set the reaction explicitly.
react_to_item
ChatGPTRecord how this person feels about a catalog item, optionally with a 1-10 rating. Resolve the item with search_catalog first — this needs our numeric id, not a title. Re-reacting replaces the previous reaction and keeps any existing rating unless you pass a new one. Pick the reaction carefully, they are not interchangeable: 'meh' means they consumed it and felt nothing; 'skipped' means they passed without engaging and is NOT a negative opinion. Only record what the person actually told you — never infer a reaction they did not state. USE 'watchlisted' FOR EVERY SAVE-FOR-LATER REQUEST, whatever the person calls it. The app renames that one shelf per medium — Watchlist (movies, TV), Read List (books), Playlist (music, games, podcasts, creators) — so "add it to my playlist" and "put it on my reading list" are both this reaction, NOT a custom list.
remove_from_queue
ChatGPTRemove tracks from this person's up-next queue by entry_id (from get_queue). Never touches history.
report_catalog_problem
ChatGPTFile a problem that a human has to action by hand: a DUPLICATE that should be merged into another entry, or an item that shouldn't be in the catalog at all. Both need a note explaining the reasoning — nobody will action one without it. Use suggest_item_edit for anything that is just a wrong field value. Removal is for genuine mistakes (a nonexistent work, a broken import), never for something the person merely dislikes.
save_profile_portrait
ChatGPTSave a written taste portrait to this person's Interestnaut profile. Its reading replaces the profile summary and is shown publicly whenever their profile is public. Use it when they ask you to write, update or emphasize their profile. Ground it in get_taste_profile and get_my_reactions plus what they have told you in this conversation; never invent titles. The headline replaces the short summary atop their profile and the reading replaces the longer one. Write declaratively, as statements about how the world is seen through their taste ("Ideas need room to spread out: …"), never "you" or "they"; direct and observant: name real titles and the tensions between them. No flattery, no horoscope language, no clinical or diagnostic claims. Show them the text and get a yes before saving. Saving replaces the current portrait; the previous one is kept and can be restored in the app.
search_catalog
ChatGPTSearch the Interestnaut catalog by keyword across one or all media types. Returns descriptive metadata and a link to each item's page. Use this to resolve a title the user mentioned into a concrete item id before calling other tools.
search_keywords
ChatGPTBrowse the controlled genre/theme vocabulary for a media type. Contributions accept only these exact terms — anything else is dropped. An empty query returns the common head of the list, which is usually enough to pick from.
search_music
ChatGPTSearch music by TRACK, ARTIST and ALBUM as separate fields. Use this instead of search_catalog whenever the person names an artist or an album — it can express 'this album by this artist', which a plain keyword search cannot. Fields combine with AND: passing artist and album returns that artist's tracks on that album. Pass only what you actually know; a wrong guess in one field filters out the right answer.
send_home_suggestions
ChatGPTSend up to 10 catalog-verified recommendations and short explanations to the user's private Home for seven days. Use only when the user asks to send these picks. Replaces the previous assistant batch for this medium; does not change reactions, ratings, or lists. Resolve IDs with search_catalog/search_music and check the user's existing reactions first. Explanations must summarize taste evidence, fit, and caveats, not hidden reasoning. Include only source links actually consulted.
set_station
ChatGPTSteer this person's endless station — the thing that keeps their queue topped up to 20 as songs finish, with no further calls from you. Describe the sound in prompt (mood, genre, era, energy), name up to 10 seed songs that capture it, and list words to avoid (artists, genres). Re-tuning replaces only the station's own picks; anything queued by name stays. enabled=false stops it.
suggest_item_edit
ChatGPTPropose a correction to an EXISTING catalog item — a wrong year, a missing creator, genres that don't fit. Queued for human review, credited to this person; it changes nothing they see until an admin approves it. ARTWORK AND LINKS ARE EDITABLE TOO, and missing cover art is one of the most useful things to fix: send a direct https image URL as image (aliases like poster/poster_url/cover/artwork are accepted), a backdrop_url for the wide still, a trailer_url, a youtube_id, or an external id such as tmdb_id. The full list of accepted names is in the field description below. Keep them distinct: the poster is the portrait cover, backdrop_url is the landscape still, and sending one as the other breaks every card that shows it. Only movies, TV and games have a backdrop. Only correct facts you are confident are wrong, and prefer to check with the person before filing. Never fill a blank field with a guess — a missing value is better than a wrong one in a catalog other people rely on.
suggest_new_items
ChatGPTPropose catalog items that are MISSING from Interestnaut, credited to this person. Accepts several at once. Nothing is published — every item is reviewed by a human first, and until then only this person can see it. ALWAYS search_catalog first and only propose what genuinely isn't there; a near-duplicate under a variant spelling is the most common mistake by far. Read get_contribution_schema and resolve genres/themes with search_keywords before calling this, or the item will be rejected for having no valid terms. Give facts you are confident about and leave the rest out. Do not guess a year, a creator, or an external database id — a wrong fact costs a reviewer more than a missing one.