Notes, Playlists & Portfolios

These tools answer questions like:

• "Save this thesis about TSMC for later"
• "What did I write about semiconductor supply chains last month?"
• "Add NVDA, ASML, and TSMC to my chip watchlist"
• "How is my Tech portfolio performing?"
• "What drove my portfolio's return in Q1?"

---

Tools at a glance

Tool	What it does	Write?
write_note	Save a research note to your knowledge base	✅ Write
query_notes	Recall notes by semantic meaning or entity	Read
get_note	Read the full body of a saved note by id	Read
list_playlists	List your stock watchlist playlists	Read
create_playlist	Create a new playlist	✅ Write
add_to_playlist	Add tickers to a playlist	✅ Write
remove_from_playlist	Remove tickers from a playlist	✅ Write
list_portfolios	List your portfolios	Read
portfolio_context	Deep portfolio analysis — returns, attribution, composition	Read

Everything here is owner-scoped — you only ever read and write your own data.

---

Notes

write_note — Save to your knowledge base

Saves a note that persists across conversations and is linked to the entities it's about — tickers, themes, GICS codes, portfolios. This is the tool that makes the AI a long-term research partner, not just a one-session assistant.

The note becomes retrievable later by entity or meaning: "show me my notes on TSMC" or "what did I write about foundry manufacturing?" both work.

When the AI saves a note:

• After a substantive investment answer — a thesis, a dated market read, a sector explainer, a comparison table
• When you explicitly say "save this" / "จดไว้"

What makes a good note:

• Tables stay as tables (markdown | syntax) — not flattened into prose
• Absolute column headers (FY2025, not Latest)
• Entity links filled in: stocks, megatrend_ids, gics — these make the note findable by interest later

Key params:

Param	Description
subject	Short title for the note
body	Full content in Markdown — preserve tables and structure
summary	One-sentence gist for scanning
note_type	reference, tracking, thesis, or decision
tags	Free-text tags
stocks	MarketDX ticker(s) this note is about
mentioned_stocks	Tickers only referenced in passing
megatrend_ids	Node ids from find_megatrend — link a theme note to the graph
gics	GICS code(s) for a sector note
agent	Which app is writing: Claude, Claude Code, ChatGPT, etc.

---

query_notes — Recall notes by meaning or entity

Searches your personal notes in two ways:

Semantic recall — q="what did I say about foundry manufacturing?" finds notes by meaning, cross-language.

Structured filters — narrow to a specific entity:

• stock — notes about a ticker (use relation="direct" for notes about it vs merely referencing it)
• theme — theme name → resolved to megatrend node, subtree included
• gics — GICS code
• tag — a tag you used when saving
• note_type — thesis, reference, tracking, decision
• since — 30d or an ISO date

Returns note summaries with similarity scores — not the full body. Call get_note(id) to read the full content.

---

get_note — Read the full note

Returns the complete body of a saved note by its id (from query_notes results). Owner-scoped — 404 if it's not your note.

---

Playlists

A playlist is a curated list of tickers that drives your news feed. Follow themes, track competitors, or manage a personal watchlist.

list_playlists

Lists all your playlists — id, name, emoji, item count, and items. Call this first whenever you want to add to or manage a specific playlist by name — match the name yourself, since the user might mis-spell it.

create_playlist

Creates a new playlist. Don't auto-create from a possible typo — always call list_playlists first and only create when the name genuinely doesn't exist or the user confirms.

create_playlist(name="Chip Supply Chain", emoji="🔬")

add_to_playlist

Adds tickers to a playlist. Always resolve names via find_stock first — the playlist stores MarketDX tickers.

add_to_playlist(
  playlist_id=12,
  tickers=["NVDA.US", "2330.TW", "ASML.NL"]
)

remove_from_playlist

Removes one or more tickers from a playlist.

---

Portfolios

list_portfolios

Lists all your portfolios: id, name, base currency, account type, NAV, total return, unrealized PnL, and position count.

Call this first whenever someone says "my portfolio" without a number — show the names and let them pick.

---

portfolio_context — Deep portfolio analysis

The most comprehensive portfolio tool. Returns a full LLM-ready snapshot of one portfolio for direct analysis.

Default view (no window):

• meta — portfolio info
• summary — key stats at a glance
• lifetime block — all-time performance (return/CAGR/Sharpe/Sortino/drawdown) + attribution + positions + composition
• recent block — same but for the last ~12 months

Windowed view (from_/to or window): Replaces lifetime+recent with one window block scoped to that period. This is how you answer period-specific questions: "how did the portfolio do in Q1?" or "compare H1 2025 vs H1 2026".

:::warning Period questions require re-calling with a window The default/lifetime/recent blocks do not contain an arbitrary period's performance. To answer "how did the portfolio do in Q1 2026?" you must call portfolio_context again with from_="2026-01-01" and to="2026-03-31". Never derive a specific period's return or attribution from the default view — those numbers aren't in it. :::

Key params:

Param	Description
portfolio_id	From list_portfolios
from_ / to	ISO date range to scope the analysis
window	Shorthand: 7d, 30d, 90d, 180d, 1y, mtd, qtd, ytd
snapshots	Composition granularity: year, quarter, month, week, day, off

What the analysis covers:

• attribution.contributors[] — per-holding PnL contribution + % of NAV change for the period; includes since-sold positions. Reconciles to nav_change to the cent.
• composition — point-in-time holdings at each snapshot date
• flags — auto-detected risk flags (concentration, drawdown, behavior patterns)
• inferred_behavior — AI-inferred portfolio style/bias

:::info Cost portfolio_context costs 5 credits. :::

---

Routing guide

You want to…	Use
Save this analysis for later	write_note
"What did I write about TSMC?"	query_notes(stock="TSMC")
"What did I write about foundry manufacturing?"	query_notes(q="foundry manufacturing")
Add stocks to a watchlist	list_playlists → add_to_playlist
See your portfolios	list_portfolios
"How is my portfolio doing?" (news pulse)	portfolio_pulse (see Pulse)
"What drove my portfolio's return in Q1?"	portfolio_context(from_=..., to=...)