Interestnaut

Add 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.

Remove 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 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).

What 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.

DISPLAY 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.

Read 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.

Read 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.

Read 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.

This 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.

Set 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.