Clarifo

Project a financial metric forward for a US or Nordic company, deterministically from its own filed history, with a read on fit quality. Chart: per the server "Charts" guidance; in ChatGPT call render_chart(source_tool="forecast_financials", source_args=<same arguments>, output="python"). Args: company: Name or ticker (fuzzy), e.g. "Apple", "AAPL". metric: ``"revenue"`` (default), ``"ebit"``, ``"ebitda"`` (Nordic only), ``"net_income"``, ``"operating_cash_flow"``, ``"free_cash_flow"``. horizon: Future years (1-10, default 3). method: ``"auto"`` (default; log-linear when all history is positive and >= 3 years, else linear), ``"log_linear"``, ``"linear"`` or ``"driver"`` (uses ``growth_rate``). growth_rate: Fraction (``0.08``) or per-year list (``[0.12, 0.10, 0.08]``); applies with ``"auto"`` or ``"driver"``, ignored with ``"linear"`` / ``"log_linear"``. market: ``"nordic"`` or ``"us"``; omit to auto-detect. Returns ``{company, metric, method_used, historical, forecast, cagr, r_squared, coverage, quality_notes}``; surface ``quality_notes``. Error: ``{"error": "..."}``.

forecast_financials

Validate and render a VisualStoryContent v2 story that you authored into PNG cards. No LLM call: you write the cards from the analysis you already have; Clarifo enforces structure, palettes, chart specs and colours deterministically and drops invalid fields. Call ``get_visual_cards_guide`` ONCE before authoring (skip only when re-rendering a story you just authored with it); without it stories routinely get the wrong ``templateId``, no ``mode`` or no cover card. Story format (essentials; the guide has the full spec): Top level: ``company``, ``period``, ``industry``, ``palette`` (graphite_navy | deep_green | midnight_teal | burgundy | graphite | bone), ``language``, ``numberFormat``, ``cards`` (4-7; first = cover). Card: ``headline`` (required, <= 12 words), ``category``, ``deck``, ``lede``, ``source``, ``stat``, ``chart``, ``mode`` (A | B | C), ``templateId``, ``stats`` (<= 4), ``segments``, ``extraCharts`` (<= 2), ``quote``, ``annotations`` (<= 6). Chart types: line, area, bar, stacked_bar, bar_line_combo, waterfall, donut, world_map, table, process_steps, radial_gauge and more. Never invent image URLs. Args: visual_story_content: The story; must contain a non-empty ``cards`` list. company / period / industry / palette / language: Optional overrides of the story's own fields. aspect: ``"1:1"`` (default), ``"4:5"``, ``"9:16"``, ``"4:3"`` or ``"16:9"`` (landscape layout); invalid values fall back to ``"1:1"``. Returns: Normally a JSON summary plus one PNG image per card. Show the returned images inline as the result; do not redraw them. The summary carries ``visuals[]`` (``visual_id``, ``title``, ``placement_hint``, ``image_index``), ``visual_order``, ``render_url`` and the validated story. When the images are not visible to the user (e.g. ChatGPT, or a collapsed tool panel), share ``render_url`` as a link: it opens the same cards on clarifo.com. Never write placeholder text such as "[Insert chart here]"; refer to the visuals in the narrative. If ``render_qa`` is present, apply its ``hint`` fixes and call again. Without headless rendering: the same metadata plus ``artifact_html``. On error: ``{"error", "failure_kind"}``.

generate_visual_cards

Serve the CEO Barometer board (methodology ``ceo-tone-v2``): how upbeat or cautious CEOs sound in their own published reviews, by market, sector, size tier and company, with QoQ / YoY, the dominant tone dimension and the market trend. It measures tone, not company performance. Reading the numbers: * ``index`` is on a 0-100 scale. 50 = the average tone of Nordic companies in 2020-2023 (not a neutral midpoint or a percentage). Tone bands: >= 57 ``pos``, <= 27 ``neg``, else ``neu``. * ``jev_scores`` (0-4, with ``jev_confidence``) are six dimensions rated by a third-party model (TypeSafe Jev): confidence, demand, profitability, growth_ambition, caution, external_blame. Silence scores lowest; caution and external blame lower the index. * ``jev_evidence`` explains each displayed column (1-10) with a verified quote. ``uncertain: true``: the two raters disagree on the band; do not present a ``stale: true`` cell as the explanation. * Do not compare markets by level: US rows come from shareholder letters (``genre: us_letter``), Nordic rows from CEO reviews. ``trend_constant_composition`` is the like-for-like trend. Args: period: period_end ``YYYY-MM-DD``; default the newest period with enough reporters. company: One company (US: lowercase ticker; Nordic: name); adds ``company_signal``. include_themes: Backward compatibility only. include_companies: Return the full ``companies[]`` (default off). include_trend_members: Per-period membership, for custom subsets (heavy; default off). history_periods: Trend points to keep (default 4; 0 = all). Returns: ``{market, period, periods, release, distribution, sectors, markets, cap_tiers, companies[], trend[], company_signal?, trend_members[]?}``. ``release`` is ``"locked"`` or ``"provisional"`` (kept off the trend).

get_ceo_barometer

Get key financial figures for one company as a yearly series (revenue, gross profit, operating income, net income, EPS, assets, equity, operating cash flow, capex) plus ``latest_period``, the freshest annual or quarterly figures. US (NYSE, NASDAQ) and Nordic (HEL, STO). For line items use ``get_financial_statement``; for several companies, ``compare_companies``. Args: company: Name or ticker, e.g. "Apple", "AAPL"; fuzzy matching. years: Annual years in ``by_year`` (default 5, max 10). market: ``"nordic"`` or ``"us"``; omit to auto-detect. period_type: ``"auto"`` (default; newest annual or quarterly), ``"annual"``, ``"quarterly"`` (adds ``by_quarter``) or ``"both"`` (``by_year`` plus ``by_quarter``). quarters: Quarters in ``by_quarter``. Nordic: default 12, max 40. US: default 8, max 20; US Q4 is derived as FY - (Q1+Q2+Q3) and flagged ``derived: true``. year / quarter: Pin ``latest_period``; ``quarter`` (1-4) forces quarterly. These are the company's OWN fiscal year and quarter (Apple's fiscal Q2 is January-March): check ``period_end``. Returns: ``entity`` (if ``entity.ambiguous``, confirm the company from ``entity.candidates``), ``by_year`` (cite its ``_provenance.citation_markdown``), ``latest_period`` and, when asked, ``by_quarter`` plus ``quarterly_coverage``. A pinned period with no data gives ``latest_period.available = false`` with ``reason: "requested_period_not_available"`` and ``nearest_available``: say so, never present another period as the one asked. Surface ``data_quality_warnings`` (Nordic PDF figure vs market-data conflicts). Chart: per the server "Charts" guidance (a line chart for a 3+ year trend); in ChatGPT call render_chart(source_tool="get_company_financials", source_args=<same arguments>, output="python").

get_company_financials

Get Clarifo's analytical profile for a company: what it does, customers and distribution, geography, strategy, key risks (with materiality) and critical accounting policies. Use for qualitative context before drilling into numbers. The profile is LLM-generated from filings (``source = "clarifo_analytical_profile"``), not filing-grade data; for filing evidence use get_financial_statement / search_filing_content. Args: company: Name or ticker, fuzzy-matched ("AAPL", "60 Degrees Pharma"). locale: "en" (default) or "fi"; an empty section falls back to the other locale. include_full_text: False (default) returns short previews per section; True returns the full narrative. Returns ``company_name``, ``updated_at``, ``overview``, ``products_services``, ``customers``, ``geography``, ``strategy``, ``risks``, ``accounting`` (text + tags), ``structured``, and ``sources`` (one ``company_profile`` card, ``evidence_strength="model_inference"``, linking to the profile page) with ``source_policy``. With no profile yet: ``error`` plus ``alternatives`` naming the tools that serve the filing data.

get_company_profile

Get a compact snapshot of a COMPANY: key financials, profile summary, entity classification, and latest filings — in a single call. Use this as the quick entry point for company-level questions. For a deeper dossier that also searches filing content, use ``research_company``. For deeper single-aspect dives, follow up with ``get_financial_statement``, ``search_filing_content``, or ``get_revenue_geography``. NOTE: this is unrelated to ``get_filing_snapshot``, which resolves a ``page_id`` into a source URL. Args: company: Company name or ticker (e.g. "Apple", "AAPL"). years: Number of recent years for financials (default 3). identifier: Alias of ``company`` (accepted for client tolerance). ticker: Alias of ``company`` (accepted for client tolerance). name: Alias of ``company`` (accepted for client tolerance). Returns: { "company_name": "Apple Inc.", "display_name": "Apple Inc.", "market": "us", "ticker": "AAPL", "entity_type": "operating", "financials": { ... }, "profile_summary": "...", "latest_filings": [ ... ], "stock_price": { "ticker": "AAPL", "price": ..., "currency": "USD", "trading_date": "...", "source": "...", "freshness_status": "live|recent|stale", "is_usable_for_live_quote": true, "age_trading_days": 0 } } ``stock_price`` is the most recent close from Clarifo's local price stores (delayed, typically T-1) and is attached whenever one exists — check ``freshness_status`` before presenting it as current. For an explicitly live/refreshed quote, follow up with ``get_stock_price`` (optionally ``require_live=true``); for a price chart, ``get_stock_price`` with ``days=N``.

get_company_snapshot

Resolve one ``page_id`` to a viewable filing source (page PNG or SEC link) for citations. This is a citation tool, not a company tool: for a company overview use ``get_company_snapshot``. ``page_id`` comes from search_filing_content hits and Nordic get_financial_statement cells; pass the bare id, not a ``clarifo://filing/...`` URI. Never print the raw ``page_id`` (or a ``[page_id: ...]`` marker) to the user; print ``citation_markdown``: a Markdown link when ``available=true``, plain ``citation_label`` text when ``available=false`` (never invent a link to a page with no preview). Args: page_id: Bare page id, e.g. ``"722df34e9f191a97518a8560755cb9e9_20"``. dpi: Render resolution for Nordic PNGs (default 150). include_text: Return the page's full indexed text under ``page_text``. Search excerpts often stop mid-sentence; read the full text before stating what a policy says. adjacent_pages: With include_text, pages on each side (0-2). max_chars_per_page: Default 12000, max 30000 (``truncated: true``). highlight: The figure as printed on the page ("229,4") or a short verbatim quote; ``citation_markdown`` then opens the page with it highlighted. Use it for every figure-level citation. Returns ``available``, ``kind`` (rendered_png | snapshot_endpoint | edgar_link | viewer_link), ``snapshot_url``, ``company_name``, ``year``, ``document_type``, ``page_number``, ``citation_label``, ``citation_markdown``, ``source_policy``; ``reason`` when unavailable. With include_text: ``page_text`` rows and ``page_text_coverage.missing`` (pages with no indexed text: say so rather than guess).

get_filing_snapshot

Get a full financial statement (income statement, balance sheet or cash flow) with line-item detail, for US (SEC XBRL) and Nordic (HEL, STO; ESEF annual filings) companies, in one shape for both. For a compact KPI summary use ``get_company_financials``. Each metric carries ``metric_name`` (filing label), ``metric_name_en`` for US companies (use it for display), value, unit and currency. Nordic companies have annual line items only: a quarterly request returns a ``quarterly_line_items_not_available`` error with alternatives (``get_company_financials(period_type="quarterly")``, ``search_filing_content``). Args: company: Name or ticker, e.g. "Apple", "AAPL". statement: ``"income_statement"`` (default), ``"balance_sheet"`` or ``"cash_flow"``. years: Most recent periods to return (1-25, default 10). market: ``"nordic"`` or ``"us"``; omit to auto-detect (the Nordic result wins when both exist). period_type: ``"annual"`` (default), ``"quarterly"`` or ``"auto"`` (US: both mixed, newest first; Nordic: annual with a ``note``). year / quarter: Filter to the company's OWN fiscal year / quarter (1-4), not calendar periods: check each period's ``period_end``. min_coverage: Drop periods below ``"complete"`` (>= 80% of core line items), ``"partial"`` (30-79%) or ``"sparse"``; omit to keep all and read each period's ``coverage_status``. Returns: ``periods[]`` (``year``, ``quarter``, ``coverage_status``, ``missing_core_metrics``, ``metrics``) with per-figure ``source_url``, ``coverage_summary``, ``sources[]`` and ``source_policy``. Cite with ``sources[].citation_markdown``; never print a raw ``page_id``. US quarterly periods carry no filing link. On miss: ``{"error", "company", "tried_markets"}``.

get_financial_statement

Industry-level valuation + profitability benchmark: the median and p25/p75 spread of P/E, P/B, EV/EBITDA, EV/EBIT, margins, ROE and revenue growth across the industry's peer set. **Use this** to answer "what does industry X trade at?", "is company Y cheap vs its industry?", or "how wide is the valuation spread in this sector?" — without rerunning a full industry analysis. The numbers are computed deterministically and stored by Clarifo's industry analysis; this tool reads the latest stored snapshot from the last 120 days. Args: industry: Industry name or group key (e.g. ``"gold miners"``, ``"gold_miners"``). Resolved via the industry synonym mapper. market: Market scope the benchmark was computed for — ``"all"`` (default), ``"us"``, ``"stockholm"``, or a ``+``-joined combination. Use ``"all"`` unless the user asks for one market. Returns: ``{industry_group, industry_display_name, market, as_of_date, year, peer_count, constituents, stats:{metric:{count,median,p25,p75,...}}, median_ev_ebitda, median_pe, median_pb, median_roe, median_ebit_margin}`` — or ``{"error": "no_benchmark_stored", ...}`` with ``alternative_tools`` (screen_companies, screen_companies_multi, value_company, get_sector_peer_set) when no recent benchmark is stored for that industry/market. Benchmarks are computed offline; this tool cannot trigger one.

get_industry_valuation_benchmark

Get a company's revenue split by country and region for one fiscal year: where revenue comes from, market exposure, geographic concentration. For totals, margins or trends use ``get_company_financials``. US (10-K XBRL) and Nordic (HEL, STO; annual reports) companies; values in millions of the reporting currency. Args: company: Name, ticker or CIK, e.g. "Apple", "AAPL"; fuzzy matching. year: Fiscal year; default the most recent annual filing. Returns: ``countries[]`` (with ISO alpha-2 codes), ``regions[]`` (own labels such as "EMEA", not expanded into countries) and ``other[]`` (the filer's "other countries" bucket, never broken down), each row with ``revenue`` and ``page_id``; plus ``currency``, ``unit``, ``total_revenue``, ``additive_layer`` and ``total_revenue_reconciliation``. Layers overlap (a "Europe" row and a "Germany" row describe the same revenue), so never sum all rows: ``total_revenue`` is the one layer named in ``additive_layer``, and coverage of group revenue below 1.0 is normal. Prefer country rows for analysis and relay ``overlap_warning`` when present. ``{"error": ...}`` when the company is unknown or has no geography data. Chart: per the server "Charts" guidance (horizontal bars of shares when the split is the point); in ChatGPT call render_chart(source_tool="get_revenue_geography", source_args=<same arguments>, output="python").

get_revenue_geography

Return a curated peer set for a sector/country workflow. Coverage today: one preset, ``nordic-construction`` (Finnish and Swedish listed construction companies). There are no US presets yet — for US peer groups use ``screen_companies`` (``index="sp500"`` / ``industry`` / ``tag_slugs``) or pass an explicit list to ``compare_companies`` / ``screen_metric_trend``. Any other sector or ``countries=["US"]`` returns ``sector_preset_not_found`` with the available presets. Args: sector: Sector key. Currently ``"construction"`` maps to the curated ``nordic-construction`` preset when FI/SE/Nordic countries are requested. countries: Optional country filter, e.g. ``["FI", "SE"]``. The returned peer set is filtered to these countries when provided. preset: Optional explicit preset slug, e.g. ``"nordic-construction"``. Returns: ``{sector_scope, peer_set, available_presets}``. ``peer_set`` entries include ``input``, ``resolved_name``, ``ticker``, ``country``, ``sector_tag``, ``resolution_source`` and ``resolution_status`` so the caller can audit the universe before running comparisons.

get_sector_peer_set

Retrieve US company segment metrics across fiscal periods, for one company or 2–5 side by side. company: one US company name or ticker; companies: 2–5 names or tickers to compare. metric: revenue, operating_income, gross_profit, assets or depreciation_amortization. axis: business, product, geographic, consolidation or a raw XBRL axis. periods: most-recent rows per segment (default 8); year pins the fiscal year. member_filter: case-insensitive substrings of labels or raw XBRL members; named members are found across axes (e.g. NVIDIA Data Center). One company: returns segments plus available_axes (the axes and members it reports). Several: returns companies, not_found and coverage_notes; segment definitions differ between issuers. Filing evidence references point into sources[]. Reads stored SEC XBRL data only.

get_segment_financials

Stock price for a listed company: latest close or a historical series. Supply ``ticker`` or ``company_name`` (at least one). Mode is automatic: - Latest (``days=0`` and no dates, default): most recent completed- session close via web search, with ``freshness_status`` (``live`` / ``recent`` / ``stale``), ``is_usable_for_live_quote``, ``age_seconds`` and ``age_trading_days``. Cached for ``prefer_cache_seconds``; ``force_refresh=true`` bypasses. With ``require_live=true`` a stale result fails with ``failure_kind="stale_price"`` and ``best_observation``. - History (``days>0`` or ``start_date`` / ``end_date`` as YYYY-MM-DD, dates take precedence): daily closes from Clarifo's database (T-1, up to 1825 days) as ``series`` of ``{date, close, volume}`` plus ``summary`` (total_return_pct, high/low, ``significant_moves`` >= 5 %). Chart: per the server "Charts" guidance; in ChatGPT call render_chart(source_tool="get_stock_price", source_args=<same arguments>, output="python"). To explain a move in a window, combine with ``company_events``, ``search_filings`` and ``search_filing_content`` for those dates. Args: share_class: Pick a share class where a company lists several. Returns (latest): ``{ticker, price, currency, trading_date, source, freshness_status, ...}``; (history): ``{company, ticker, currency, period, summary, series}``. Error: ``{"error", "failure_kind"}``.

get_stock_price

Return historical valuation multiples for a listed company. Each data point represents P/E, P/B, P/S, EV/EBITDA, EV/EBIT, EV/Sales and FCF yield as of one trading day, pre-computed from that day's closing price and the latest annual fundamentals. Data is delayed by one day (up to yesterday). At least one of ``company_name`` or ``ticker`` must be supplied. ``days`` controls the lookback window (default 365, max 1825). Returns ``{company, ticker, data_points, period, series}`` where ``series`` is a list of daily multiples snapshots. **Rendering:** when the trend matters, draw a static line chart (x=date, one line per multiple) from ``series`` yourself per the server's "Charts" guidance (Clarifo theme, source line ending "Clarifo calculation"; no widgets). In ChatGPT (with output="python") or a host that cannot draw: ``render_chart(source_tool="get_valuation_history", source_args={...same args...})``. On error: ``{"error": "...", "failure_kind": "..."}``.

get_valuation_history

Read the full content of a single item from one of your workspaces. Covers workspaces you own and workspaces shared with you (user taken from the authenticated MCP session, access enforced). Long text bodies are capped to keep the response lean — ``content_truncated`` flags when that happened. Args: workspace_id: The workspace the item belongs to. item_id: The item's id (from ``list_workspace_items``). Returns: {"item_id": ..., "type": "report", "title": ..., "content": {...}, "content_truncated": false, "unfinished": false, ...} On miss / no access: {"error": "..."}.

get_workspace_item

DEF 14A proxy data for US companies: board, named-executive pay, CEO pay ratio, say-on-pay. Three modes: - ``"snapshot"`` (default): one company's proxy, latest or for ``fiscal_year``. "What does Apple's CEO earn?" - ``"trend"``: multi-year board composition and pay for one company. - ``"peer"``: rank an explicit peer set (``companies``) on one ``metric``; there is no index or sector filter. Args: company: Name, ticker or CIK; required for snapshot and trend. companies: Peer set (2+ names, tickers or CIKs); required for peer. fiscal_year: Snapshot / peer; omit for the most recent proxy. years / from_year / to_year: Trend rows (newest first, default 8, max 25) and fiscal-year bounds. metric: Peer: ``"ceo_pay_ratio"`` (default), ``"ceo_total_pay"``, ``"board_independence"``, ``"female_director_ratio"``, ``"median_employee_pay"`` or ``"sop_percent_for"``. direction: Peer: ``"desc"`` (default) or ``"asc"``. Returns: Snapshot: ``{company_name, ticker, cik, proxy {fiscal_year, board, executive_compensation, insider_ownership, say_on_pay, ceo_pay_ratio, source_url}}``. Trend: ``{..., trend[]}``. Peer: ``{metric, direction, peers[], companies_not_resolved, coverage, missing}``.

governance

SEC Form 4 insider trading for a US company. Three modes: - ``"summary"`` (default): counts and net USD by reporter class (``c_level`` = officers and directors, vs 10% owners) and transaction type; pass ``granularity`` for a per-period trend. "Is the CEO buying?" - ``"clusters"``: cluster trades, several distinct officers or directors trading the same direction within a rolling window (after Cohen, Malloy and Pomorski), ranked by ``conviction_score`` (insiders, size, recency). Descriptive, not a recommendation. - ``"transactions"``: raw Form 4 rows, newest first. Args: company: Name, ticker or CIK. since_date / until_date: ``YYYY-MM-DD`` (default last 365 days; ``until_date`` unused in clusters). include_derivatives: Include option grants / exercises (default False; summary and transactions). granularity / periods: Summary trend, ``"quarter"`` or ``"month"``; ``periods`` caps buckets (max 60). direction: Clusters: ``"purchase"`` (default) or ``"sale"``. window_days / min_insiders / min_total_value / top_k / include_raw: Clusters: window 1-365 (default 90), insiders >= 2 (default 2), USD floor, clusters kept (default 5; 0 = all), pre-dedup windows. transaction_types / reporter_class / reporter_cik / limit: Transactions: subset of purchase, sale, award, exercise, other; ``"officer"``, ``"director"``, ``"ten_pct_owner"`` or ``"c_level"``; one insider; row cap (default 50, max 1000). Returns: Summary: ``summary {transaction_count, net_value_usd, by_type, by_reporter_class}`` and ``sources[]`` (at most the 1,000 newest transactions), or ``trend[]``. Clusters: ``clusters[]``, each with a ``source_ref`` into ``sources[]``. Transactions: ``transactions[]`` with an EDGAR ``source_url`` per row.

insider_activity

List the items in your own Clarifo workspace (notes, uploaded files, analyses, reports), including work that is still in progress. Covers workspaces you own and workspaces shared with you (share link or your Team) — the user is taken from the authenticated MCP session. Returns item metadata and a short preview, not full bodies; use ``get_workspace_item`` for an item's content. Args: workspace_id: Which workspace to read. Omit to use your workspace automatically; if you have several, the tool returns the list of workspace ids to choose from. only_unfinished: When true, return only items still in progress (files whose text is still being extracted, drafts, pending/generating items). types: Optional filter, e.g. ``["file", "report"]``. Valid types: text, source, analysis, search_result, chat_message, report, file, spreadsheet, visualization. limit: Max items to return (1–200, default 50). Returns: {"workspace_id": "...", "total": 12, "items": [ {"item_id": "...", "type": "file", "title": "Q3 deck.pdf", "processing_status": "pending", "unfinished": true, "preview": "...", "updated_at": "..."} ]} If you have multiple workspaces and none was specified: {"needs_workspace_id": true, "workspaces": [...]}. If not authenticated: {"error": "..."}.

list_workspace_items

Draw a Clarifo chart of a result you already fetched. Three outputs: - ``output="python"`` — **ChatGPT and any host with a python / code tool.** Returns a ready-to-run matplotlib script with every number, label, colour and the source line embedded server-side. Run it unchanged in your python tool; it ends with ``plt.show()``, which makes the chart appear in your answer. Do not edit the numbers, do not save the figure to a file and never write a Markdown image link (````) — it renders as a broken image. - ``output="image"`` (default) — a PNG image block, for hosts that show MCP images to the user inline (Claude). ChatGPT does NOT show MCP images to the user: use ``output="python"`` there. - ``output="chart_spec"`` — the validated chart as JSON (periods, one series per metric with its unit, formula and figure basis, per-period citations, quality warnings, a text alternative). For a host that draws charts itself: plot these values exactly and print the warnings; it does not guarantee the host shows an interactive chart. All three are built from one spec, so they always show the same metrics, periods and figures. Call it only when a chart earns its place (a trend over 3+ periods, a peer comparison over time, a ranking of 4+ names, a sensitivity grid); a single figure or a two-row comparison needs a sentence or a table. For several metrics of one company pass ``metrics`` (e.g. ``["revenue", "operating_margin"]``: revenue bars on the left axis, the margin as a line on a labelled right axis); a peer comparison takes one metric per call. Only the named metrics are drawn — an unknown metric, or one the result has no values for, is an error, never a substitute. Years with no value for any charted metric are left off the axis; interior gaps stay gaps. Pass the name of the tool you called and **the same arguments you passed it**. The data is re-fetched and the chart is computed server-side from Clarifo's stored data — never pass figures yourself, there is no parameter for them. For ``get_stock_price`` pass the history-mode arguments (``days`` or a date range); without them that tool performs a live latest-close web lookup. Chartable tools: ``compare_companies`` (multi-year: one line per company for ``metric``, calendar-year aligned; single period: KPI table), ``forecast_financials``, ``get_company_financials``, ``ownership`` (all three modes), ``get_revenue_geography``, ``get_stock_price`` (history mode, i.e. with ``days`` or a date range), ``get_valuation_history``, ``screen_companies``, ``screen_metric_trend``, ``screen_quality_growers``, ``value_company``. Args: source_tool: Name of the tool whose result to chart. source_args: The arguments you passed to that tool, verbatim. metric: Which metric to chart where the source carries several (``compare_companies``: ``revenue`` (default), ``operating_margin``, ``net_income``, ``gross_margin``, ``free_cash_flow``, ...). ``get_company_financials``: ``revenue_operating_income`` draws revenue and operating income in one stacked bar per year (bar total = revenue, base segment = operating income, margin row underneath; a loss hangs below zero). Annual data only. Single-company metrics: ``revenue``, ``gross_profit``, ``operating_income``, ``ebit``, ``ebitda``, ``net_income``, ``operating_cash_flow``, ``capital_expenditures``, ``free_cash_flow``, ``total_assets``, ``total_equity``, ``eps_diluted`` (reported) and ``gross_margin``, ``operating_margin``, ``ebit_margin``, ``ebitda_margin``, ``net_margin``, ``fcf_margin`` (computed: amount / revenue). output: ``"python"`` (ChatGPT / code tools), ``"image"`` (PNG) or ``"chart_spec"`` (JSON for a host that draws natively). metrics: Several metrics in one chart (``get_company_financials``); ``metric`` alone keeps working. chart_type: ``"auto"`` (default: bars for up to 5 annual periods, a line for longer series; an amount with a margin is a ``bar_line_combo`` for up to 8 periods), ``"line"``, ``"bar"``, ``"grouped_bar"``, ``"horizontal_bar"`` or ``"bar_line_combo"`` (one company: amounts as bars, the ``%`` metric as a line on its own right axis). Applies to ``get_company_financials`` and ``compare_companies`` (combo: single company only). Returns: python: the script plus run instructions and the source line to print under the chart. image: a one-line description plus the PNG. chart_spec: the chart as data. All three carry ``quality_warnings`` to print under the chart when present.

render_chart

Analyse how an in-flight IASB / EFRAG reporting project affects companies, grounded in their filings. Deterministic (no LLM spend). Known projects: "Risk Mitigation Accounting" (DRM), "IAS 28 Fair Value Option Amendments", "IFRS 20" (rate-regulated activities), "ESRS-40a" (ESRS for non-EU groups); an unknown project returns the valid list. IFRS projects apply to IFRS reporters; US-GAAP filers are mainly in scope of ESRS-40a. Modes (any other value = assess): - ``"assess"`` (default): one company's scope assessment, baseline evidence with verification states, gap assessment and unresolved questions. Without ``company``: the project card and evidence checklist. - ``"screen"``: exposure across a universe, per company likely_relevant / potentially_relevant / no_public_evidence_found / likely_not_relevant / not_assessable, with confidence and reasons. - ``"card"``: article-ready roadmap card (eight sections, from What changed to Confidence) plus ``visual_cards_outline``. Args: project: Name, id or alias, e.g. "IFRS 20", "DRM", "ESRS-40a". company: Name or ticker; assess target, card filing example. companies: Explicit list (max 15) for screen / card. industry / country ("US", "FI", "SE", "Nordic"): screen / card filters, ignored when ``companies`` is given. top_n: Universe size for screen / card (default 10, max 15). assess_depth: "full" (default) or "scoping" (scope signals only). as_of: Optional assessment date. Returns ``official_sources``, ``filing_sources`` / ``evidence`` and ``source_policy`` in every mode, plus ``publication_gate`` (assess) and ``methodology_audit`` (screen). Cite ``citation_markdown`` verbatim, never raw ``page_id`` strings.

reporting_change

Company research in one call: structured financials, filing-text search per topic, and the analytical profile, run in parallel for one resolved company. Use for broad questions ("tell me about D.R. Horton", "why did KB Home's revenue decline?", "NVIDIA's key risks?"); use the individual tools for one narrow item (just the balance sheet, one filing's text). Args: company: Name or ticker, fuzzy-matched ("DHI", "Apple"). topics: Filing-text topics to search (max 5; 3 when concise). Default: revenue trajectory, risks, outlook. year: Restrict the filing search to one fiscal year. years: Annual periods of financials (default 3, max 5). concise: Top hit per topic, short snippets, profile overview and risks only (about 70% smaller). Returns ``company``, ``financials`` (``by_year``, ``latest_period``, ``data_quality_warnings``; the same figures get_company_financials gives; ``latest_period.metrics_available: false`` / ``superseded_period`` when the newest period has no figures yet), ``filing_content`` by topic, ``profile``, ``sources`` (cite their ``citation_markdown``), ``source_policy``, ``summary`` and ``integrity_warnings`` when a block was dropped. ``year`` is the fiscal year closing at ``period_end``; ``period_label`` reads "FY2025" / "Q3/2025".

research_company

Resolve a batch of company names/tickers to canonical entities. Use this **before** running per-company analysis on a list, so the downstream loop drives off CIKs/canonical names rather than the user's raw strings (avoiding the per-tool fuzzy-match drift that used to put two companies into a single ``research_company`` response). The resolver is cached, so a hot list — say the same five S&P 500 industrials called repeatedly — costs effectively zero on the second invocation. Args: companies: List of inputs to resolve (max 50; entries beyond the first 50 are ignored). Each entry can be a ticker ("DHI", "AAPL"), an official name ("HORTON D R INC /DE/"), or a brand name ("D.R. Horton", "Google"). Order is preserved in the response. Returns: { "resolved": [ { "input": "DHI", "name": "HORTON D R INC /DE/", "cik": "0000882184", "ticker": "DHI", "market": "us", "confidence": 1.0, "source": "ticker_exact" }, ... ], "unresolved": ["TOTALLY_UNKNOWN_TICKER"], "total": 6, "matched": 5 }

resolve_entities

Score one company's CEO review now with the CEO Barometer method (``ceo-tone-v2``: same review text, TypeSafe Jev battery and calibration), so ``index`` is directly comparable with ``get_ceo_barometer`` (0-100, 50 = average Nordic tone in 2020-2023; >= 57 positive, <= 27 cautious). Pro-plan tool; the review text is sent to the external Jev API. Nothing is persisted and no quote or rationale is written: column explanations exist only for published rows (``get_ceo_barometer`` ``jev_evidence``). ``published`` says whether the board already has a row for the period and whether it was scored from identical text. Args: company: US: lowercase ticker. Nordic: lowercase company shortname. Matched exactly. year: Reporting year; default the freshest period. quarter: 1=Q1, 2=H1, 3=Q3, 4=FY; used only with ``year``. language: Backward compatibility only; results are language-neutral. Returns: ``{company_name, period_end, market, index, tone, dominant_dimension, jev_scores (0-4), columns (1-10), published, persisted: false, ...}``, or ``{"error", "available_periods"}`` when there is no CEO review for the period.

score_ceo_sentiment_for_company

Rank or screen companies by one financial metric ("which S&P 500 companies grew revenue most in 2025?"). For one company use ``get_company_financials``. Chart: per the server "Charts" guidance; in ChatGPT call render_chart(source_tool="screen_companies", source_args=<same arguments>, output="python"). Args: metric: e.g. ``revenue``, ``ebit``, ``ebitda``, ``net_income``, ``operating_cash_flow``, ``free_cash_flow``, ``marketcap``; IFRS line items (``total_assets``, ...); Nordic KPIs (``order_book``, ``equity_ratio``); ratios ``gross_margin``, ``operating_margin``, ``ebit_margin``, ``net_margin``, ``ebitda_margin``, ``fcf_margin`` (0.25 = 25 %). US lacks ``marketcap``, ``free_cash_flow`` (use ``fcf_margin``) and the Nordic KPIs. US ``ebitda`` is operating income + D&A and ``fcf_margin`` is (OCF - capex) / revenue; companies without a D&A or capex line are left out, never zeroed. mode: ``"growth"`` (default, YoY %) or ``"value"`` (alias ``"level"``). year: Anchor fiscal year; omit for the latest with data. compare_years: Growth mode: years back (default 1). country: ``"US"``, ``"FI"``, ``"SE"`` or ``"Nordic"`` (all Nordic issuers in one call; do not call per country). Omit for all; value mode then mixes currencies (use ``value_anchor_eur``). industry: Free-text substring. tag_slugs: precise taxonomy filter. top_n: 1-100 (default 20). direction: ``"desc"`` (default) / ``"asc"``. min_value: Floor on ``value_anchor`` (native currency). include_types: ``"operating"``, ``"holding"``, ``"reit"``, ``"bank"``, ``"investment_vehicle"``; ``["operating"]`` excludes banks/REITs/holdings. index: ``"sp500"``; forces ``country="US"``. ``growth_pct`` is null when a value is negative; use ``trend`` and ``delta_absolute`` instead. Returns ``companies`` (``value_anchor``, ``value_compare``, ``growth_pct``, currency) and ``coverage`` (``total_in_scope``, ``with_data``, ``returned``). Surface ``coverage_warning`` and ``data_quality_warning`` / ``excluded_data_quality`` (rows withheld for an implausible scale or currency change).

screen_companies

Screen companies by up to five financial criteria in one call; only companies passing ALL filters are returned. Each filter scans the top 100 companies for its metric and the lists are intersected, so companies outside a filter's top 100 are not seen. Args: filters: List of filter objects (max 5): ``metric`` (required, as in ``screen_companies``), ``mode`` (``"growth"`` default or ``"value"``), ``growth_min`` / ``growth_max`` (%, growth mode), ``value_min`` / ``value_max``, ``compare_years`` (default 1). E.g. ``[{"metric": "revenue", "growth_min": 15}, {"metric": "ebit", "mode": "value", "value_min": 0}]``. ``marketcap`` is Nordic-only and sparse; prefer ``revenue`` for size. country: ``"US"``, ``"FI"``, ``"SE"`` or ``"Nordic"`` (also ``"Nordics"``/``"Scandinavia"``; one call, do not call per country). Omit for all markets. include_types: Entity types; ``["operating"]`` excludes banks, REITs and holdings. top_n: Max companies (default 20). rank_by: Index into ``filters`` used for ranking (default 0). index: ``"sp500"``; forces ``country="US"``. Returns ``{filters_applied, companies, coverage: {passed_all, returned}}``; ``passed_all`` counts matches within the scanned top-100 lists only.

screen_companies_multi

Multi-period time series of one financial metric across a peer group, each cell traceable to one filing period ("how has Costco's operating margin moved vs. Walmart and Target?"). Chart: per the server "Charts" guidance; in ChatGPT call render_chart(source_tool="screen_metric_trend", source_args=<same arguments>, output="python"). Pick companies either with ``peers`` (names or tickers, Nordic and US mixed) or by ranking the top ``top_n`` by ``rank_metric`` within ``countries`` / ``industry`` / ``tag_slugs``. Args: metric: ``revenue``, ``gross_profit``, ``ebit``, ``ebitda``, ``net_income``, ``operating_cash_flow``, ``free_cash_flow``; margins ``gross_margin``, ``operating_margin``, ``ebit_margin``, ``ebitda_margin``, ``net_margin`` (computed deterministically; ``ebit_margin`` uses EBIT, ``operating_margin`` the IFRS operating profit line); plus granular IFRS line items (annual only). US EBITDA is operating income + D&A; companies without D&A drop out. peers: Explicit list; ranking filters are then ignored. countries: e.g. ``["FI"]``, ``["SE"]``, ``["DK"]``, ``["US"]`` or a combination; omit for all markets. industry: Free-text industry substring. tag_slugs: taxonomy filter. top_n: Ranked group size (1-50, default 8). window: Periods in the series (2-16, default 5). anchor_year: Latest period; omit for the latest available. frequency: ``"annual"`` (default) or ``"quarterly"`` (Nordic only). rank_metric: Ranking metric (defaults to ``metric``). strict_resolution: Fail on ambiguous peer names instead of choosing. Returns ``{metric, unit, frequency, periods, companies, series_data, chart_series, coverage}``; error: ``{"error": "..."}``.

screen_metric_trend

Multi-year pattern screens over reported annual figures (not a recommendation). Equivalent to several ``screen_companies`` calls intersected. ``pattern="quality_growth"`` (default): passes when revenue CAGR over ``compare_years`` >= ``min_revenue_cagr``, EBIT is positive and its margin improving (checked only where both margins exist), operating cash flow is positive, and the entity type is operating. ``pattern="turnaround"``: prior trouble in T-3..T-1 (losses, EBIT margin down >= 3 pp, or revenue drop) and improvement in the latest fiscal year. Only country, industry, stage, min_revenue_eur and top_n apply. To confirm a candidate, check ``search_filing_content`` for restructuring language. Chart: per the server "Charts" guidance; in ChatGPT call render_chart(source_tool="screen_quality_growers", source_args=<same arguments>, output="python"). Args: country: ``"US"``, ``"FI"``, ``"SE"`` or ``"Nordic"`` (also ``"Nordics"``/``"Scandinavia"``; one call, do not call per country). Omit for all markets. min_revenue_cagr: Minimum revenue CAGR in % (default 10). compare_years: Look-back years (default 3). max_marketcap: Native currency, Nordic only and sparse; on a US or unscoped screen it returns no companies. top_n: Max results (default 20). stage: turnaround only: ``"early"`` or ``"confirmed"``; omit for both. industry: turnaround only, e.g. ``"automakers"``. min_revenue_eur: turnaround only, latest revenue floor (default 20 000 000). Returns ``companies`` with ``quality_metrics`` (revenue_cagr_pct, ebit margins, operating cash flow) and ``coverage``; turnaround rows carry ``turnaround_score`` (0-100), ``stage``, ``signals``, ``prior_trouble``, ``series`` and ``trace``, with thresholds in ``rules``.

screen_quality_growers

Rank stored US company segment rows by metric value or year-on-year growth. metric: revenue, operating_income, gross_profit, assets or depreciation_amortization. axis: business, product, geographic, consolidation or a raw XBRL axis. year/quarter: CALENDAR year and quarter in which the period ended (quarter 1–4 forces quarterly; NVIDIA's Q2 FY2027, ended 2026-07-26, is year=2026 quarter=3); rows carry fiscal_period. Omitted: the newest period in scope. compare_years: growth lookback. screen_mode: value or growth; growth bounds are percentages, value bounds are USD. member_filter: case-insensitive label/member substrings. companies: explicit universe; industry: keyword or keyword list; index: sp500. include_types: operating, bank, reit, holding or investment_vehicle. top_n: 1–100 rows; direction: desc or asc. Returns ranked rows, coverage and inline SEC filing source URLs. Reads stored data only; no external search or mutation.

screen_segments

Semantic search within the full text of company filings (annual and interim reports, stock exchange releases, SEC filings) for qualitative questions: strategy, risk factors, guidance, accounting policies. Covers US (NYSE, NASDAQ) and Nordic (HEL, STO) filings. Results are ranked by meaning, not keywords: check each result's company_name, and put synonyms (and for Nordic filings, local-language terms) in the query. Args: company: Name or ticker, fuzzy-matched ("DHI", "D.R. Horton"). A company named only in the query is auto-detected (``resolution.auto_detected``); set it explicitly to be certain. year: Fiscal year. quarter: 1-4; unpopulated for part of the corpus, so use only for one quarter's interim report. document_type: "annual_report", "interim_report", "stock_exchange_release", "10-K", "10-Q"; aliases normalized. market: "us" or "nordic"; omit to auto-detect. With no company or index the search covers Nordic filings only (``market="us"`` alone returns nothing). index: Only "sp500" (forces US, queries every constituent). Cannot be combined with ``company``. limit: Passages to return (default 5, max 20). max_total_results caps rows after adjacent-page expansion. include_adjacent_pages: Also return the page before and after each Nordic hit (``is_adjacent_page``, ``supports: "context"``), for policy text that spans pages. For a full page use ``get_filing_snapshot`` with ``include_text=true``. topic_tags / ifrs_tags: Restrict to pages tagged with these concepts (deterministic; unknown values are ignored and reported back). Topics are snake_case, e.g. leases, goodwill, impairment, segment_reporting, risks_uncertainty, strategy_outlook, ceo_review, dividends, sustclimate. IFRS (Nordic only): "IAS 1" .. "IAS 40", "IFRS 1" .. "IFRS 18", e.g. "IFRS 16". auto_detect_tags: Default True: with no explicit tags, tags are detected from the query. A tag filter matching nothing is retried untagged (``tag_filters.applied: false``). response_mode: "detailed" (default) or "concise" (drops long excerpts, keeps citation fields); use "concise" across several companies. Returns ``results`` (``content``, ``page_id``, ``page_number``, ``evidence``, ``citation_markdown``, ``source_url``), ``sources``, ``source_policy``, ``resolution``, ``tag_filters``, and a ``diagnostic`` when nothing is found. Keyword-fallback hits (pages not yet vectorised) carry ``retrieval: "keyword"``. Cite with ``citation_markdown`` verbatim; ``page_id`` is only for follow-up calls (``get_filing_snapshot``) and never shown to the user.

search_filing_content

Search company filings (SEC 10-K / 10-Q / 8-K, annual and interim reports, stock exchange releases), or with ``mode`` the report calendar and the earnings season. To read a filing's text use search_filing_content. Modes: - ``"filings"`` (default): documents with ``fiscal_year``, quarter, ``document_type``, ``docid``, ``period_end`` (safe for cross-company timelines) and ``filed_date``; ``year_from`` / ``year_to`` filter on fiscal year. ``market="us"`` with no company lists all US filings. - ``"calendar"``: scheduled report dates in ``from_date``..``to_date`` (default today .. +14 days, max 120), optionally one ``company`` or ``market``; ``published: true`` once the report is in Clarifo. Never extend the calendar with guessed dates. - ``"season"``: a calendar quarter's earnings season (``year_from`` + ``quarter``, default the latest ended): breadth and medians of revenue / margin / EPS change, sectors, outliers, largest still to report. Shares and medians are over ``coverage.with_revenue_growth`` (companies with figures so far), not all ``coverage.reported``; name that base. ``company`` = comma-separated watchlist, ``to_date`` = as-of date. - ``"reported"``: one row per company and period with ``released_at`` (US: the earnings 8-K), ``filed_at`` (10-Q / 10-K), ``status`` (released | filed), US figures and growth (``figures_source`` = xbrl | release_table). Default window the last 30 days. Any "share that grew" is over ``counts.with_revenue_growth`` ("12 of the 15 with figures so far"); ``counts.sp500_universe`` gives "x of 500". Args: company: Name or ticker, fuzzy-matched ("DHI", "D.R. Horton"). document_type: "annual_report", "interim_report", "stock_exchange_release", "10-K", "10-Q", "8-K". market: "nordic" (HEL, STO, OMXH) or "us" (NYSE, NASDAQ); omit for both. Season also takes "fi"/"HEL", "se"/"STO", "all" (default us). quarter: 1-4 with year_from = the calendar quarter the period ended in. index ("sp500"), status, min_revenue_growth_pct, sort: reported mode; sort = reported_at (default), revenue, revenue_growth_pct, net_income_growth_pct, eps_growth_pct, company. sector: Season and reported, GICS sector(s), comma-separated. from_date / to_date: YYYY-MM-DD. limit: Default 20, max 100. offset: max 1000, with ``has_more``. Returns ``filings`` (calendar: ``events``; reported: ``rows``), ``total`` (this page), ``total_available``, ``has_more``, ``resolution``.

search_filings

Valuation of a Nordic or US company, from trailing multiples to a DCF. Results are model estimates, not investment advice. Unset assumptions are derived from filings (WACC via CAPM, growth via FCF CAGR) and echoed in ``assumptions`` / ``inputs``. Modes (``mode``): - ``"forward_dcf"`` (default): per-share value plus WACC x growth grid; uses wacc, fcf_growth, terminal_growth, forecast_years (3-15), fade_years (0-15), use_forecast, include_peer_triangulation. - ``"reverse_dcf"``: what the price implies; ``solve_for`` ``"growth"`` (default) or ``"wacc"``. - ``"implied_expectations"``: per-share value grid over x_axis / y_axis from ``revenue_cagr``, ``operating_margin``, ``fcf_margin``, ``terminal_growth``, ``wacc``, ``fcf_conversion``, ``tax_rate``; optional x_values / y_values and ``base_*`` overrides. - ``"multiples"``: P/E, P/B, P/S, EV/EBITDA, EV/EBIT, EV/Sales, FCF yield (P/FFO for US REITs); uses only company, market, current_share_price, shares_outstanding. Chart: per the server "Charts" guidance; in ChatGPT call render_chart(source_tool="value_company", source_args=<same arguments>, output="python"). Args: company: Name or ticker. market: ``"nordic"`` / ``"us"``; omit to detect. Rates are fractions (``0.09`` = 9 %): wacc, fcf_growth, terminal_growth, risk_free_rate, equity_risk_premium, tax_rate, cost_of_debt. current_share_price: omit to use the latest stored daily close. beta, shares_outstanding, net_debt, minority_interest: overrides. locale: ``"en"`` (default) or ``"fi"``. Returns ``valuation`` / ``reverse`` / ``sensitivity_grid`` / ``multiples`` per mode, with ``quality_notes``. Surface ``sector_fit``: ``"unsuitable"`` (banks, insurers) means the DCF is illustrative only.

value_company

Return the full authoring guide for ``generate_visual_cards`` (markdown). Call this ONCE before authoring a ``VisualStoryContent v2`` object. It documents everything the validator accepts — all 20 rich templates with when-to-use guidance, every chart type (including ``radial_gauge``), annotations, key-figure tiles, segment rows, quotes, image effects, the editorial house rules (one card = one claim, headline/lede length budgets, no repetition) — and a gold-standard example story to pattern-match against. Static content, no database or LLM call. Costs nothing on Clarifo's LLM budget.

get_visual_cards_guide