Newsmind

One feed's metadata — id, title, URL, folder, last poll time, error status. For all the user's feeds, use get_feeds.

get_feed

Fetch the full content of a single article by ID, including read/starred status. Lazy-fetches via Mozilla Readability if the feed only had a summary (slower on first call; cached afterward).

get_article

Return articles published since the user's last check, oldest-first, and atomically advance the per-token cursor. Use this for 'what's new since I last asked?' across separate conversations — Claude doesn't need to remember anything; the server tracks the cursor per token. First call defaults to the last 24 hours. **Pagination.** If the response includes `has_more: true`, call again with the same args to fetch the next batch — the cursor has already advanced past what was returned, so subsequent calls pick up where the previous one left off. Loop until `has_more: false` to drain the full unread set when the user asks for 'everything'. **Peek mode.** Pass `mark_seen=false` to return articles without advancing the cursor — use when you want to preview what's new before committing to having shown it (e.g. user might cancel the conversation, you want to retry on a transient error). A subsequent call with `mark_seen=true` (the default) advances the cursor. **Filter.** Pass `exclude_feed_ids` to skip one or more feeds — typical use is 'what's new minus Hacker News' when a high-volume firehose feed is dominating the queue. **Proactive feed-health.** When the response includes a `feed_warnings` field (only present when at least one of the user's feeds is in the poller's give-up state, error_count ≥ 3), surface it to the user in your reply — e.g. "by the way, N of your feeds aren't being fetched; run get_feed_health for details or unsubscribe_from_feed to remove dead ones." Don't mention when the field is absent (healthy account = no noise). **Watch summaries.** When the response includes a `watch_summaries` field (only present when the user has saved watches), mention any watch with `new_match_count > 0` to the user — e.g. "by the way, your Fellow watch has 3 new matches." The user can then ask for detail, which you fulfill by calling `get_watch_matches(watch_id=…)`. Don't mention watches with 0 new matches.

get_new_articles

Return articles the user has marked read, most-recently-read first. Use when the user asks 'what have I read', 'show my reading history', 'what did I read about X last week'. Subject to tier retention — articles past the retention window are pruned and won't appear. feed_id narrows to one source; since_days narrows by read_at (when the user read it), not publish date.

get_reading_history

Return the user's starred articles, newest-starred first. Use when the user asks 'what have I starred', 'show my starred articles', 'what did I save this week', or wants to revisit favorites. Subject to tier retention — articles starred but past the retention window (Pro 30d / Max 90d) are not returned, since stars do not bypass retention. feed_id narrows to one source.

get_starred_articles

Get unread articles, most recent first. Use for 'what's new', 'what landed today', 'show me recent articles' — anytime the user wants recency without a specific topic. `since_hours` narrows to a recent window (e.g. 12 for 'since this morning', 24 for 'today'); `feed_id` narrows to one source; `exclude_feed_ids` drops one or more feeds (e.g. 'what's new minus Hacker News' if HN is dominating the queue). Prefer this over search_articles_by_keyword when there's no keyword to search on. For 'what's new since I last asked' across separate conversations, prefer get_new_articles. **Topic clustering.** When the user asks to group their unread by topic, story, or theme, call this tool with `lean: true` and a high `limit` (up to 1000) to fit the entire unread set in one call. Then read the titles, identify story threads (e.g. '17 articles on the iOS 26.5 release rollout', '6 articles on the Musk-Altman trial'), and surface them. Pair with mark_articles_read to bulk-clear a thread the user has already covered elsewhere. **Engagement ranking.** Pass `boost_engaged_feeds: true` when the user wants their most-relevant news first rather than strict reverse-chronological — e.g. 'what should I read', 'what's worth my time', 'the good stuff first'. It re-orders the recent unread pool so feeds the user actually reads and stars float to the top and habitually-skipped feeds sink, with recency as the tiebreaker. Leave it off (default) for a pure newest-first timeline.

get_unread_articles

Total unread count, scoped to subscribed feeds within tier retention (Pro 30d, Max 90d). Cheap — no article data. Pass `by_feed: true` to also get per-feed breakdown (which sources are noisy). Use BEFORE get_unread_articles when only a count is needed; great for 'how many unread' and 'where are my unread'.

get_unread_count

Pull the unseen matched articles for the user's watches (from watch_hits, newest-detected first). With watch_id, runs one watch; without, runs all and groups results by watch. By default marks the returned articles as seen so the next call only shows new ones; pass mark_seen=false to peek. Use when the user asks 'what's new on my watches', 'show me the M5 Mac mini matches', or after seeing watch_summaries on get_new_articles. Each article includes matched_at (when detected) and, for semantic watches, a similarity score.

get_watch_matches

Bulk-subscribe to feeds from an OPML 2.0 document. Use when the user pastes OPML XML or names a few feeds at once. **Hard cap: 100 entries per call** — for larger imports (Feedly/Inoreader exports etc.) direct the user to https://newsmind.app/auth/account where they can upload an OPML file of any size. Idempotent: already-subscribed feeds are skipped. Returns immediately after format-validating + queueing; actual fetching runs in the background at ~10/min. Call get_import_status to track progress.

import_opml

List all RSS feeds the user is subscribed to. Returns id, title, URL, last poll time, and any error status.

get_feeds

Return the user's saved watches with scope, delivery, active state, and current unseen-match counts. Use when the user asks 'what am I watching', 'show me my watches'. Read-only — does NOT mark anything seen.

list_watches

High-water mark — marks every unread subscribed article published at or before `through_published_at` as read. When the user says 'mark all read' or 'I'm caught up', pass the current UTC time (ISO 8601) — articles arriving later remain unread, no race window. Optionally scope to one feed with `feed_id` ('mark all from MacRumors as read').

mark_all_articles_read

Bulk undo — restores every read subscribed article published at or before `through_published_at` to unread state. Optionally scope to one feed. Use when the user says 'never mind, I want to re-process those' or 'put everything back to unread'.

mark_all_articles_unread

Mark specific articles as read by ID. Use when the user is responding to a list you just showed them — 'mark the first three', 'mark everything you just listed'. For 'mark all read' / 'I'm caught up' use mark_all_articles_read instead.

mark_articles_read

Restore specific articles to unread state by ID. Use when the user marked something read by accident or wants to revisit it later. Sets `read_at` to NULL on the underlying `reads` row; preserves any star.

mark_articles_unread

Reorganize an existing subscription into a folder. Omit `folder` to remove the feed from any folder (top-level). Does not affect the feed's articles, subscribed_at cutoff, or unread queue.

move_feed_to_folder

File a bug report, feature request, or feedback to the Newsmind team. Use this when the user expresses frustration with how a tool worked (a discovery returned nothing they expected, an action didn't do what they intended, an error message was confusing), asks for a feature that doesn't exist, or volunteers feedback they want the developers to see. Include reproducer details: what they asked, what tool you called, what came back, what they expected. Don't include the user's API token, JWT, or any other credential — the server scrubs them defensively but reports should be clean. Returns an issue ID the user can reference if they email support.

report_issue

Full-text keyword search across all subscribed articles. Returns {articles: [...], fallback?: 'or', hint?: string, retention: {window_days, cutoff_at, cutoff_hit?}}. Articles are ranked by keyword relevance with a 14-day recency half-life — best matches first, with a mild bias toward recent articles. For newest-first ordering without a topic ('what's new today', 'show me the latest'), use get_unread_articles instead — this tool requires a non-empty query. Compound-query handling: when an AND search ('Apple battery EU AI regulation') returns no articles, the tool automatically retries with OR semantics and tags the response with fallback='or' — narrate the reduced precision to the user. The hint field is a human-readable note explaining what happened when the result set is empty or fell back. **Retention field** — `retention.window_days` is the user's tier cap (Pro: 30, Max: 90); `retention.cutoff_at` is the ISO date past which we can't see. `retention.cutoff_hit: true` appears when retention likely bounded the result set (user passed since_days > window, empty result for a multi-term query, or oldest article sits at the wall) — when present, tell the user something like "these are the matches within your plan's N-day retention window". Don't mention retention when cutoff_hit is absent. For multi-concept questions where you want both topics covered, prefer running multiple narrower queries and merging the results, or use search_articles_by_meaning if available (Max-only).

search_articles_by_keyword

Conceptual / semantic search across all subscribed articles. Use when the user asks for an idea, theme, or concept that may not match exact keywords (e.g. 'unintended consequences of AI regulation', 'companies pivoting away from open source'). Prefer over search_articles_by_keyword for compound or paraphrased questions where keyword overlap with article text is unlikely — e.g. 'GPU bottleneck' should match articles about 'AI chip supply', 'frontier safety' should match 'AGI alignment'. Returns {query, count, articles, retention: {window_days, cutoff_at, cutoff_hit?}} — articles ranked by meaning, not exact word match; never empty unless the corpus itself is empty. The retention field carries the Max 90-day cap and a cutoff_hit flag when the wall likely bounded results — relay that to the user on "go back as far as possible" style queries. Included in the Newsmind Max plan only — calls from other plans return a plan_required error; use search_articles_by_keyword instead in that case.

search_articles_by_meaning

Mark one or more articles as starred (saved/favorited). To remove a star, use unstar_articles instead.

star_articles

Add an RSS/Atom feed to the user's subscriptions. The feed will be polled automatically. `url` may be either the actual feed URL or a regular site/homepage URL — if the URL returns HTML, the server auto-discovers the feed via `<link rel="alternate" type="application/rss+xml">` (or atom+xml) in the HTML head, so the user can paste e.g. https://stratechery.com/ instead of having to find the .xml URL. When auto-discovery fires, the response includes `auto_discovered: { input_url, discovered_url }` — relay this to the user ("I subscribed you to X, which I found via the link tag on Y"). Only articles published after the subscribe show up in discovery tools (unread queue, search, counts) — historical articles already in storage are filtered out by the per-subscription `subscribed_at` cutoff. Re-subscribing to a feed you already have is a no-op; to reorganize an existing subscription's folder, use move_feed_to_folder.

subscribe_to_feed

Remove the starred mark from one or more articles. Deletes the row from the `stars` table; does not touch read state.

unstar_articles

Remove a feed from the user's subscriptions. Does not delete shared articles. Pass the feed's numeric id (from get_feeds or any article's feed_id) when you have it; you may also pass the feed's exact title or URL and it will be resolved against the user's subscriptions. If nothing matches, the response has status 'not_found' — call get_feeds and retry rather than guessing an id.

unsubscribe_from_feed

Modify a saved watch without recreating it. Use to pause/resume (active=false/true — 'mute my M5 watch'), rename, edit the query, change scope, or switch delivery channel/cadence. Only the fields you pass are changed. Editing the query rebuilds the match set. Returns the updated watch.

update_watch