Save to the user's Clarifo workspace, only when the user asks: an analysis you wrote as a new document (title + markdown), a company onto one of their watchlists (add_company), or, only when the user asks to, a company off one watchlist (remove_company with portfolio_id), or a company's position in a portfolio or watchlist (set_position). Never changes or deletes a document or a whole list.

Position: set_position is the company; give one of shares (the new total), add_shares (bought; negative = sold) or weight_pct (Clarifo works out whole shares from the latest close and the other positions; tell the user the shares and result weight it returns), optionally cost_per_share. Where a portfolio's shares come from its trades, the change is recorded as a buy or sell dated today and needs cost_per_share (the trade price): ask the user for it. Say the before and after in a sentence, then show the list with open_in_clarifo(portfolio_id=...) (the user can keep editing there) instead of pasting portfolio_url; give the link only when asked.

Watchlist: add_company is a name or ticker; Clarifo resolves it strictly and says which company it added (tell the user; a near miss returns not_found, so ask for the ticker). portfolio_id comes from portfolios; with several lists and none given, the result lists them: ask the user. new_watchlist creates a watchlist of that name (or uses the user's list of that name). An investment portfolio gets the company as a member only, without shares.

Document:

For a results review, a company analysis or a portfolio report, first call with report_type and no markdown: nothing is saved, the result is the brief (sections, word targets, the Clarifo tools to gather from, house style) and save_to, the workspace it would go to (or needs_workspace_id with the list: ask the user before writing). Write to it and save with the same report_type; a draft under the brief's minimum is not saved and comes back with the brief.

For a report about a portfolio, pass portfolio_id: it is saved in the portfolio's workspace. With several workspaces and none given, nothing is saved and the result lists them.

Clarifo saves the text as written; figures are not checked against the sources. Point the user to editor_url. Formatting and length findings are kept in the document's review panel in Clarifo, not in the text. Visual Cards ride along as given.

Args: idempotency_key: Optional; leave it out. Clarifo recognises a repeated identical request by its content. Give one only to retry this same request. title: Document title. markdown: The analysis, without the title. Headings, paragraphs, lists (nested by indenting), > callouts, pipe tables, ---, bold, italic, https links, and figures as an image on its own line: , and charts as a ```chart block of JSON (format in the brief). Cite a filing page by writing its page_id in brackets, e.g. [<page_id>], right after the claim. Markdown the editor cannot read comes back in formatting_findings: fix it with apply_document_update. sources: The page_ids the analysis rests on (from Clarifo's search and filing tools). Only these become citations. companies: Companies the analysis is about (up to 5); the document is linked to them. workspace_id: Target workspace; omit when the user has one, or give portfolio_id for the portfolio's workspace. With several, the result lists them: ask the user. new_workspace: Instead of workspace_id, the name of a workspace of the user's own to save into, created if they have none of that name (within the account's workspace limit). Only when the user asks for a new workspace. folder: Folder name; created if it does not exist. visual_story_content: Optional Visual Cards for the document, the same story generate_visual_cards takes. from_note_id: The note (from notes) this document was worked up from; the note keeps a link to the document. seo: Publishing settings {"title" (search title, up to 60 characters), "description" (up to 155), "slug" (URL words, e.g. "nokia-q3-2026-results")}. Each one left out is derived from the title and first paragraph; the user reviews them in the editor. cover_image: {"url": https image address, "alt": what it shows}: the document's cover, also its social sharing image. report_type: "earnings_review" (a results review, about 400-650 words), "company_analysis" (a full analysis, about 2500-6000 words) or "portfolio_report" (one portfolio, about 600-1500 words). Without markdown: the brief. target_words: Only when the user names a length: about how many words. It replaces the brief's length (the draft may run 25% short of it); pass it with the brief call too. language: ISO 639-1 code of the language the document is written in ("en", "fi", "sv"); with the brief call, the brief asks for it. Stored with the document. translation_of: The item_id of the user's document this one translates (with language): the two are linked. add_company: Watchlist mode: the company (name or ticker) to add. portfolio_id: Watchlist mode: the list to add to (from portfolios). Document mode: save in this portfolio's workspace. new_watchlist: Watchlist mode: instead of portfolio_id, a watchlist name; created if the user has none of that name. For a new list in a user with several workspaces, also workspace_id. note: Watchlist mode: an optional note on the company, e.g. why the user wants to follow it. remove_company: The company (name or ticker) to take off the watchlist portfolio_id, which is required. Confirm the company and the list with the user first. Investment portfolios are changed in Clarifo. set_position: Position mode: the company (name or ticker) whose position changes on portfolio_id (from portfolios; may be omitted when the user has one list). A company not yet on the list is added with shares. shares: Position mode: the new number of shares; 0 removes the position and keeps the company as followed. add_shares: Position mode: shares bought (negative: sold). weight_pct: Position mode: the target weight in % of the list's value, the other positions unchanged. cost_per_share: Position mode: the average cost per share; with add_shares the price paid, blended into the average; for trade-based portfolios the trade price. follow: The company (name or ticker) the user wants to follow, as Clarifo's Follow button does (portfolios(following=true) lists them; Automated Insights read them). Not a portfolio: no list, no position. On its own call. unfollow: The company to stop following, only when the user asks.

Returns: {"status": "document_saved", "item_id", "editor_url", "missing_sources", "formatting_findings", "structure", "visual_cards": {"kept", "left_out"}} or {"status": "company_added" | "already_in_portfolio" | "company_removed" | "not_in_portfolio", "company_name", "ticker", "portfolio_name", "portfolio_url"} or {"status": "position_updated" | "trade_recorded" | "no_change", "company_name", "before", "after", "weight", "trade", "portfolio_url"} or {"status": "company_followed" | "already_followed" | "company_unfollowed" | "not_followed", "company_name", "ticker"} or {"needs_workspace_id" | "needs_portfolio_id": true, ...} or {"error", "failure_kind"}.