Clarifo

Project a financial metric forward for a company, with the historical series it is built on and an honest read on fit quality. Works for both Nordic (HEL, STO; ESEF/iXBRL) and US (NYSE, NASDAQ; SEC EDGAR) companies. The projection is deterministic — no LLM arithmetic — and every forecast point is anchored to the company's own filed history. **Rendering:** this result is chartable but nothing draws it automatically. When the projection is worth showing, follow up with ``render_chart(source_tool="forecast_financials", source_args=...)`` passing the same arguments — it draws a line chart with solid history and a dashed projection. Otherwise present ``historical`` and ``forecast`` as a table and summarise ``cagr``, ``r_squared``, and ``quality_notes`` in prose. Methods: - ``"auto"`` (default): log-linear (compounding) when all history is positive and there are ≥3 years, else a linear fit. - ``"log_linear"``: force the compounding model (requires positive history). - ``"linear"``: ordinary least squares on the raw values. - ``"driver"``: you supply the growth assumption via ``growth_rate`` (forced automatically whenever ``growth_rate`` is set). Args: company: Company name or ticker. Examples: "Apple", "AAPL", "Neste", "Kemira". Fuzzy matching supported. metric: One of ``"revenue"``, ``"ebit"``, ``"ebitda"``, ``"net_income"``, ``"operating_cash_flow"``, ``"free_cash_flow"``. (``ebitda`` is Nordic-only.) horizon: Number of future years to project (1–10, default 3). method: ``"auto"`` (default), ``"log_linear"``, ``"linear"`` or ``"driver"``. growth_rate: Driver assumption as a fraction. Either a single value (e.g. ``0.08`` for 8% every year) or a list of per-year fractions (e.g. ``[0.12, 0.10, 0.08]``). When set, ``method`` is forced to ``"driver"``. market: Restrict to ``"nordic"`` or ``"us"``. Omit to auto-detect. Returns: { "company": "Apple Inc.", "market": "us", "metric": "revenue", "method_used": "log_linear", "frequency": "annual", "historical": [{"year": 2021, "value": ...}, ...], "forecast": [{"year": 2025, "value": ...}, ...], "cagr": 0.11, "r_squared": 0.98, "horizon": 3, "coverage": {"history_points": 5, "first_year": 2020, "last_year": 2024}, "quality_notes": [...] } On miss: ``{"error": "..."}``.

forecast_financials

Validate + render a VisualStoryContent v2 object **you authored** — no LLM call. **REQUIRED FIRST STEP — call ``get_visual_cards_guide`` before this tool.** The guide is a static, no-cost markdown returner that documents every template with when-to-use guidance, all chart types (including ``radial_gauge``), annotation grammar, editorial rules and a gold-standard example story. Stories authored without reading the guide routinely miss the design vocabulary — wrong ``templateId``, missing ``mode``, unbalanced ``stats``, no cover card — and the renderer then falls back to defaults that drop most of the design intent. Skip the guide only for a follow-up render of a story you *just* authored in the same turn using the guide's rules. You (the caller) already have the analysis in context, so author the cards yourself and pass them here. This tool runs them through the Clarifo visual-cards house rules deterministically — structure, palettes, themes, chart specs and per-card colours all come from Clarifo and are enforced server-side — and returns a ``VisualStoryContent v2`` object the Clarifo frontend renders. No provider is called, so this costs nothing on Clarifo's LLM budget. Nothing off-brand can ship: an invalid field is dropped and the renderer falls back to its default. Typical flow: (1) call ``get_visual_cards_guide`` to load the authoring rules; (2) gather data with the read tools (``research_company``, ``get_company_financials``, ``search_filing_content`` …); (3) author the ``VisualStoryContent v2`` JSON per the guide; (4) call this tool. **Authoring contract (only these are read; everything else is dropped):** Top level:: {"company", "period", "industry", "palette", # one of: graphite_navy | deep_green | midnight_teal | # burgundy | graphite | bone "language", # "fi" | "en" "numberFormat": {"locale":"en","currency":"EUR","scale":"auto","decimals":1}, "cards": [ ... ]} # 4–7 cards; the FIRST is the cover Each card:: {"kind": "data", # card 0 is forced to "cover" "category": "GROWTH", # short ALL-CAPS eyebrow "headline": "...", # REQUIRED (≤12 words) — no headline, no card "deck": "...", # optional subhead ≤90 chars "lede": "...", "outcome": "...", "source": "...", "stat": {"value": "+12%", "label": "NI revenue YoY", "raw": 0.12}, "chart": { ... }, # see chart payloads below "mode": "B", # optional A (white) | B (dark navy) | C (beige) "templateId": "chart_brief", # optional, allowlisted (see guide) "stats": [{"value":"48","label":"plants"}], # ≤4 key-figure tiles "segments": [{"icon":"shopping_cart","title":"Grocery", "figure":"52%","figureLabel":"of EBIT"}], # image_split_stats rows "extraCharts": [{"title":"EBIT","chart":{...}}], # ≤2, chart_grid panels "quote": {"text":"...","source":"CEO, Q1 call"}, # both fields required "annotations": [{"text":"19% CAGR","kind":"trendline", "anchor":{"kind":"series","series":0,"index":0}, "anchorTo":{"kind":"series","series":0,"index":2}, "emphasis":"positive"}], # ≤6, cartesian charts only "mirror": true} # two-column templates: chart left Template allowlist: process_journey | process_serpentine | process_stickers | hero_donut | duo_circles | sunrise_split | waffle_stat | quote_poster | statement_highlight | chart_brief | orbit_feature | company_profile | chart_grid | heatmap_ladder | minimal_pulse | image_hero | image_split | image_split_stats | feature_grid | metric_gauge. Image templates auto-fill ``imageUrl`` with a curated on-industry photo — never invent URLs. Chart payloads (``chart.type`` ∈ line | area | bar | stacked_bar | bar_line_combo | donut | world_map | table | process_steps | radial_gauge | none):: bar: {"type":"bar","unit":"%","bars":[{"label":"NI","value":12}]} line/area: {"type":"line","xLabels":["2024","2025"], "series":[{"name":"Revenue","points":[4.3,4.5]}],"unit":"€B"} stacked_bar: {"type":"stacked_bar","xLabels":[...], "segments":[{"name":"MN","values":[10,9]}]} bar_line_combo: {"type":"bar_line_combo","xLabels":[...], "bars":{"name":"Revenue","values":[19.2,19.4]}, "line":{"name":"Margin","values":[9,11],"unit":"%"}} donut/table/ {"type":"donut","slices":[{"label":"EMEA","value":42}], world_map: "centerLabel":"Revenue","unit":"%"} # world_map: "zoom":true process_steps: {"type":"process_steps", "steps":[{"title":"Recognise","description":"...", "icon":"real_estate_agent"}]} # 2–7 steps radial_gauge: {"type":"radial_gauge","value":87,"min":0,"max":100, "target":90,"unit":"%","caption":"Utilisation"} # metric_gauge template only Palette is always re-resolved to a vetted catalog colour world, so the story stays on-brand even if you omit or misname it. See the ``render-visual-cards`` SKILL.md for the full schema, palette-safe colours and template allowlist. Args: visual_story_content: The object you authored. Must contain a non-empty ``cards`` list; ``company`` / ``period`` / ``industry`` / ``palette`` / ``language`` may live inside it or be passed as the args below. company: Override for the cover headline / eyebrow. period: Override for the period label, e.g. ``"Q1/2026"``. industry: Override; drives the default palette when ``palette`` is absent. palette: Override palette name. language: Override output language (``"fi"`` / ``"en"``). aspect: PNG canvas format — ``"1:1"`` (default; X / general share), ``"4:5"`` (Instagram / LinkedIn feed), ``"9:16"`` (story) or ``"4:3"`` (presentation / desktop; renders the landscape layout with the text column beside the chart). The story JSON itself is format-free — the same content renders into every aspect — so pick the aspect for where the user will use the images. Invalid values fall back to ``"1:1"``. Returns: All response paths include a ``visuals`` array and ``visual_order`` list for structured article composition. Each entry in ``visuals``:: {"visual_id": "nokia-q1-2026-growth-1", # stable slug for referencing "title": "Revenue growth surges 12%", # card headline "visual_type": "chart", # cover|chart|scorecard|heatmap|… "placement_hint": "after_growth_discussion", # where in article flow "card_index": 1, # 0-based index in cards array "image_index": 2} # 1-based content-block index (PNG path) ``visual_order`` is the list of ``visual_id`` values in recommended sequence. Use ``placement_hint`` to position visuals relative to article sections. **Never write placeholder text** like ``[Embed VisualCard: ...]`` or ``[Insert chart here]`` — the visuals are already rendered inline. Reference them naturally in narrative (``As the growth chart shows…``). When headless rendering is available (the normal case), a content list: a JSON summary text block followed by one PNG **image per card** (shown inline):: [ '{"company":"Nokia","period":"Q1/2026","card_count":5, "visuals":[{"visual_id":"…","title":"…","visual_type":"chart", "placement_hint":"after_growth_discussion","card_index":1, "image_index":2},...], "visual_order":["nokia-q1-2026-annual-review-0","…"], "render_url":"https://…","visual_story_content":{...}}', <Image card 0>, <Image card 1>, … ] Show the images as the result. **If the images do not appear inline in your response** (they may be collapsed in a tool-result panel the user does not see), always share ``render_url`` as a clickable link so the user can view the cards in a browser. ``render_url`` opens the same cards on clarifo.com (public route, no login) with download / share controls. If the summary carries ``render_qa``, one or more returned images are visually degraded (clipped text, unreadable contrast, missing icon glyphs). Each issue includes a ``hint`` with the concrete authoring fix — apply the hints to ``visual_story_content`` and call this tool again rather than showing a degraded card. When headless rendering is unavailable, a dict instead — same metadata plus ``artifact_html`` (the exact Clarifo HTML; render it as one HTML artifact, best in a real browser) and ``render_url``. Always share ``render_url`` with the user as a fallback:: {"company": "Nokia", "period": "Q1/2026", "visual_story_content": {...}, "card_count": 5, "language": "en", "palette": "graphite_navy", "source_mode": "caller_authored", "latency_ms": 3, "render_url": "…", "artifact_html": "<!DOCTYPE …", "visuals": [...], "visual_order": [...]} On error:: {"error": "...", "company": "<input>", "failure_kind": "missing_input" | "validation_failed" | "render_error"}

generate_visual_cards

Serve the CEO Barometer board: market/sector/company sentiment (−100…+100 index built from CEOs' own published reviews) plus per-company QoQ / YoY / dominant theme, and the market's trend series. Every scored theme cell is grounded in a verbatim CEO quote whose provenance has been substring-verified against the source chunk — the barometer never renders a hallucinated attribution. Args: period: Reporting period_end as ``YYYY-MM-DD`` (e.g. ``"2026-03-31"``). When omitted, anchors on the newest period that clears the minimum-reporters floor (a fresh single-filer period cannot hijack the default board). company: Optional company name (e.g. ``"Nokia"``) — when set, the response focuses on that one company via a compact ``company_signal`` block (index / QoQ / YoY / peer percentile / short trend) and restricts ``companies[]`` to matching entries. Legal suffixes (Oyj, AB, plc, …) are stripped for matching. include_themes: When true, keeps the per-company ``themes`` blob (verbatim quote + chunk_id + source per theme, one cell per company). Off by default because the blob is heavy — turn it on for a per-company drill-down, keep it off for the market view. include_companies: When true, returns the full ``companies[]`` list. Off by default so the market view is compact; ignored when ``company`` is set (the filtered ``companies[]`` is always returned then). include_trend_members: When true, returns the per-period, per-company membership blob so a widget can recompute the trend for any filter client-side. Off by default because it is heavy (dozens of periods × hundreds of companies). history_periods: How many trend points to keep, newest last. Default 4 (roughly one year of quarters). Pass 0 to keep the full trend. Returns: ``{market, period, periods, release, distribution, sectors, markets, cap_tiers, companies[], trend[], company_signal?, trend_members[]?}``. ``release`` marks the anchored period as ``"locked"`` (finalised) or ``"provisional"`` (still filling in); provisional periods are kept off the canonical trend line so a changing company set never reads as a sentiment move.

get_ceo_barometer

Get structured key financial figures for a company. Returns revenue, gross profit, operating income, net income, EPS, total assets, equity, operating cash flow, and capital expenditures as a time series grouped by year. **By default** the response also includes a ``latest_period`` section with the most recent data (annual OR quarterly, whichever is fresher) — answering "what is the latest revenue?" without requiring the caller to inspect every year. Works for both Nordic (HEL, STO) and US (NYSE, NASDAQ) companies. If ``market`` is not specified, both markets are tried automatically. **Rendering:** this result is chartable but nothing draws it automatically. When the multi-year trend is worth showing, follow up with ``render_chart(source_tool="get_company_financials", source_args=...)`` passing the same arguments. Otherwise present ``by_year`` as a formatted table and highlight ``latest_period``. **Latest-period selection (default ``period_type="auto"``):** - Apple (FY2025 ends 2025-09-27, Q1/2025 ends 2025-03-29) → FY2025 wins - Kemira (FY2024 ends 2024-12-31, Q3/2025 ends 2025-09-30) → Q3/2025 wins Args: company: Company name or ticker. Examples: "Neste", "NESTE", "Apple", "AAPL", "Microsoft", "MSFT". Fuzzy matching supported. years: Number of recent annual years to include in ``by_year`` (default 5, max 10). Does not affect ``latest_period``. market: Restrict to ``"nordic"`` or ``"us"``. Omit to auto-detect. period_type: Selection mode for ``latest_period``: ``"auto"`` (default — newest annual or quarterly), ``"annual"`` (newest fiscal year), ``"quarterly"`` (newest quarter — also adds a ``by_quarter`` time series for Nordic companies), ``"both"`` (annual ``by_year`` + quarterly ``by_quarter`` in one response). quarters: Number of most recent quarters in ``by_quarter`` (default 12, max 40). Only used when ``period_type`` is ``"quarterly"`` or ``"both"``. Each quarterly value carries provenance: ``status`` (reported_standalone/derived_subtraction/manual), ``formula`` for derived values, ``confidence``, ``validated_against_fy`` (sum-of-quarters reconciled against the annual figure) and ``source_page_ids`` resolvable via ``get_filing_snapshot``. year: Pin ``latest_period`` to a specific fiscal year. **This is the company's own fiscal year**, not the calendar year. Apple's fiscal year 2026 runs October 2025 - September 2026. Check ``latest_period.period_end`` in the response to verify which calendar period the data covers. quarter: Pin ``latest_period`` to a specific fiscal quarter (1-4). If given, ``period_type`` is forced to ``"quarterly"``. **This is the company's own fiscal quarter number, not the calendar quarter.** Apple's fiscal Q2 is January - March (calendar Q1). Always check ``period_end`` in the response to verify the actual calendar period. When the pinned period has no structured data (e.g. the quarter's report is not ingested yet), ``latest_period`` comes back as ``{"available": false, "reason": "requested_period_not_available", ...}`` with a ``nearest_available`` snapshot of the newest period that does exist — it is never silently substituted with a different period. Returns: { "company_name": "Neste Oyj", "display_name": "Neste Oyj", "market": "nordic", "by_year": { "2023": {"revenue": 21990000000, ...}, "2022": { ... } }, "latest_period": { "period_label": "Q3/2024", "period_type": "quarterly", "year": 2024, "quarter": 3, "period_end": "2024-09-30", "source": "eu_avainluvut_q", "metrics": {"revenue": {"value": 5800000000, "unit": "EUR", ...}} }, // period_type="quarterly"/"both", Nordic only: "by_quarter": { "Q2/2025": { "year": 2025, "quarter": 2, "period_end": "2025-06-30", "metrics": {"revenue": {"value": 1685000000, "unit": "EUR", "status": "reported_standalone", "confidence": "high", "validated_against_fy": true, "source_page_ids": ["<page_id>"]}} }, ... }, "quarterly_coverage": {"complete": 10, "partial": 2, "total": 12} } A ``data_quality_warnings`` list is added (Nordic only) when a PDF-extracted figure for a year conflicts with the consolidated market-data figure — e.g. a parent-company or segment revenue picked up instead of the group total. The value is still returned (not nulled); the warning names the metric, year, both figures and the divergence ratio so you can flag it rather than trust it silently. When ``year`` or ``quarter`` is pinned, this list is scoped to the pinned year — ``by_year`` still shows the full trend window, but a pinned Q2/2026 request no longer drags in warnings about unrelated FY2022-2025 figures. Call again with the flagged year pinned to see its warning. Returns ``{"error": "...", "company": "..."}`` if not found.

get_company_financials

Get Clarifo's analytical profile for a company. Returns a structured narrative covering what the company does, how it distributes, where it operates, its strategy, key risks (with materiality classifications), and critical accounting policies. Same content the company-page Overview tab renders. Use this for **discovery and qualitative context** — to understand a company before drilling into numbers, or to provide the LLM with enough business context that it can interpret the financial figures meaningfully. The profile is **LLM-generated from filings**. The response includes ``source = "clarifo_analytical_profile"`` so the caller can clearly distinguish analytical content from filing-grade data (``get_financial_statement`` / ``search_filing_content``). Args: company: Company name or ticker. Fuzzy matching is supported (e.g. "Fiskars", "FSKRS.HE", "60P", "60 Degrees Pharma"). locale: ``"en"`` (default) or ``"fi"``. The skill falls back to the other locale if the requested one is empty. include_full_text: When ``False`` (default), returns short preview texts (~1–2 paragraphs per section, much smaller token footprint). When ``True``, returns the full multi-paragraph narrative for each section. Returns: { "company_name": "60 Degrees Pharmaceuticals, Inc.", "locale": "en", "source": "clarifo_analytical_profile", "updated_at": "2025-04-01T12:00:00Z", "overview": "60 Degrees Pharmaceuticals (60P) is a U.S.-based ...", "products_services": {"text": "...", "tags": [...]}, "customers": {"text": "...", "tags": [...]}, "geography": {"text": "...", "tags": [...]}, "strategy": "...", "risks": {"text": "...", "tags": [...]}, "accounting": {"text": "...", "tags": [...]}, "structured": {...}, "sources": [ {"source_kind": "company_profile", "evidence_strength": "model_inference", "document_type": "company_profile", "citation_markdown": "[60 Degrees Pharmaceuticals, Inc. Company Profile](https://.../en/companies/...)", "source_url": "https://.../en/companies/60%20Degrees%20Pharmaceuticals%2C%20Inc."} ], "source_policy": {"citation_mode": "claim_level", "display": {...}} } The ``sources`` entry is honestly tagged as a ``company_profile`` (``evidence_strength="model_inference"``) linking to the company profile page — it is NOT filing-grade evidence. For filing-backed source verification use ``search_filing_content`` / ``get_filing_snapshot``. When the company is unknown or has no profile yet: ``{"error": "No profile found", "company": "...", "locale": "..."}``.

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. "Neste", "AAPL"). years: Number of recent years for financials (default 3). Returns: { "company_name": "Neste Oyj", "display_name": "Neste Oyj", "market": "nordic", "ticker": "NESTE.HE", "entity_type": "operating", "financials": { ... }, "profile_summary": "...", "latest_filings": [ ... ] }

get_company_snapshot

Resolve a single ``page_id`` to a viewable filing source (PNG snapshot or SEC link). This is a CITATION tool, not a company overview — for the latter use ``get_company_snapshot``. Use this for citation / transparency: every figure returned by ``get_financial_statement`` (and ``search_filing_content``) carries a ``page_id`` in ``pdf_info``. Calling this tool with that id returns the URL of the page so the answer can include a verifiable source. Behaviour: - **Nordic filing with a preview**: ``kind="rendered_png"`` and ``snapshot_url`` points to the per-page PNG preview. - **Nordic filing that can be previewed on demand**: ``kind="snapshot_endpoint"`` and ``snapshot_url`` points to the canonical snapshot endpoint. - **US filing**: ``kind="edgar_link"`` and ``snapshot_url`` points to the SEC EDGAR document. - **Preview not yet available** (older or just-ingested filings): ``available=false`` with a ``reason``. The caller can still cite ``company_name``, ``year``, ``page_number``. CITATION RENDERING — never print the raw ``page_id`` (or a ``[page_id: ...]`` marker) to the user. Print ``citation_markdown`` instead: a ready-made ``"[Company Q2 2026, p. 4](https://...)"`` Markdown link when ``available=true``, or the plain ``citation_label`` text with no link (e.g. ``"Company Q2 2026, p. 4"``) when ``available=false`` — never fabricate a link to a page that has no preview yet. Args: page_id: Page identifier returned in ``pdf_info`` from other tools. Format example: ``"722df34e9f191a97518a8560755cb9e9_20"``. dpi: Render resolution for Nordic PNG snapshots (default 150). Returns: { "page_id": "...", "available": true, "kind": "rendered_png" | "snapshot_endpoint" | "edgar_link" | "viewer_link", "snapshot_url": "https://...", "company_name": "Neste Oyj", "year": "2024", "quarter": null, "document_type": "annual_report", "page_number": 12, "dpi": 150, "citation_label": "Neste Oyj 2024, p. 12", "citation_markdown": "[Neste Oyj 2024, p. 12](https://...)" } On miss: ``available=false`` with a ``reason`` string, plus ``citation_label``/``citation_markdown`` (link-free) so the caller can still cite the page by name in plain text.

get_filing_snapshot

Get a full financial statement (income statement, balance sheet, or cash flow) for a company. Includes metric labels (Finnish for Nordic, English-translated Finnish for US) and currency annotations. Use this when you need the **line-item detail** behind the headline figures — building timelines, multi-year trend charts, or peer comparison tables. For a compact KPI summary, use ``get_company_financials`` instead. Works for Nordic companies (HEL, STO; ESEF/iXBRL annual filings) and US companies (NYSE, NASDAQ; SEC EDGAR XBRL). The output shape is identical across both markets so timeline rendering can ignore the source. **Quarterly coverage differs by market.** US companies have quarterly line items (10-Q). Nordic companies do NOT: ESEF filings are annual-only and interim reports are not ingested at line-item level, so a quarterly request for a Nordic company returns an explicit ``quarterly_line_items_not_available`` error with alternatives (``get_company_financials(period_type="quarterly")`` for headline figures, ``search_filing_content`` for interim report text). **Default behaviour without a year/quarter:** returns the latest periods of the requested ``period_type`` (annual). ``period_type="auto"`` mixes annual and quarterly rows sorted newest first for US companies; for Nordic companies it returns annual rows with a ``note`` field. Args: company: Company name or ticker. Examples: "Fiskars", "Neste", "AAPL", "Apple". statement: One of ``"income_statement"`` (tuloslaskelma), ``"balance_sheet"`` (tase), ``"cash_flow"`` (rahavirtalaskelma). Default: ``"income_statement"``. years: Maximum number of most recent periods to return (1–25, default 10). Applies to whichever ``period_type`` is chosen. market: Restrict to ``"nordic"`` or ``"us"``. Omit to auto-detect (both markets are probed concurrently; Nordic wins on a tie). period_type: ``"annual"`` (default), ``"quarterly"``, or ``"auto"`` (mixes both, newest first). year: Filter to a specific fiscal year (e.g. ``2024``). **This is the company's own fiscal year**, not the calendar year. quarter: Filter to a specific fiscal quarter (1-4). **This is the company's own fiscal quarter number, not the calendar quarter.** Apple's fiscal Q2 is January - March (calendar Q1). Always check ``period_end`` in each returned period to verify the actual calendar dates. When set, ``period_type`` should typically be ``"quarterly"`` or ``"auto"``. min_coverage: Optional per-period completeness filter. Every period is scored based on how many core line items are populated: ``"complete"`` (≥80% of core), ``"partial"`` (30–79%), ``"sparse"`` (<30%). Set to drop periods below the band — e.g. ``min_coverage="partial"`` omits the "one stray fact was ingested" case that would otherwise pose as a normal period. Omit to keep every period and rely on the per-period ``coverage_status`` field to decide. Returns: { "company_name": "Fiskars", "market": "nordic", "statement": "income_statement", "period_type": "annual", "periods": [ { "year": 2024, "quarter": null, "period": "2024", "coverage_status": "complete", "available_core_metrics": 8, "expected_core_metrics": 8, "missing_core_metrics": [], "metrics": { "revenue": { "metric_name": "Liikevaihto", "value": 1250.5, "unit": "MEUR", "currency": "EUR", "source_url": "https://.../api/pdf-snapshot?page_id=...", "page_id": "..." }, ... } }, ... ], "coverage_summary": { "complete": 3, "partial": 0, "sparse": 1, "total": 4, "core_metric_set": ["revenue", "operating_income", ...] }, "sources": [ {"citation_markdown": "[Fiskars 2024 ...](https://...)", "source_url": "https://...", "source_kind": "s3_pdf", ...} ], "source_policy": {"citation_mode": "claim_level", "display": {...}} } Each period's metric cells carry per-figure provenance — a ``source_url`` (and ``page_id`` for a Nordic PDF-snapshot page, or an ``accession_number`` for a US filing) — and the response carries a deduped top-level ``sources[]`` of cite-sources evidence cards plus a ``source_policy``. Nordic links resolve to the ESEF iXBRL viewer or a page-precise PDF snapshot; US links resolve to the SEC EDGAR filing (annual periods only — the 10-K/20-F that owns the fiscal year; quarterly US periods carry no filing link). Render ``citation_markdown`` to users; never print the raw ``page_id``. 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 persisted by the industry analysis; this tool reads the latest stored snapshot. Args: industry: Industry name or group key (e.g. ``"gold miners"``, ``"kullankaivajat"``, ``"gold_miners"``). Resolved via the industry synonym mapper. market: Market scope the benchmark was computed for — ``"all"`` (default), or a nationality-filter tag such as ``"us"``, ``"suomalainen"``, ``"stockholm"`` (or a ``+``-joined combination). Returns: ``{industry_group, industry_display_name, market, as_of_date, year, peer_count, constituents, stats:{metric:{count,median,p25,p75,...}}, headline_medians}`` — or ``{"error": ...}`` when no benchmark is stored yet for that industry/market (run an industry analysis to populate it).

get_industry_valuation_benchmark

Get a company's revenue split by country and region for one fiscal year. Use this when the question is about *where* revenue comes from — exposure to specific markets, geographic concentration, region-level shifts. For other financial questions (totals, margins, trends) use ``get_company_financials``. For broader business context use ``get_company_profile``. **Rendering:** this result is chartable but nothing draws it automatically. When the geographic split is worth showing, follow up with ``render_chart(source_tool="get_revenue_geography", source_args=...)`` passing the same arguments. Otherwise present ``countries`` and ``regions`` as a table with revenue shares. Coverage: - **Nordic** (Helsinki, Stockholm): country breakdowns extracted from PDF annual reports. Currency typically EUR or SEK, in millions. - **US** (NYSE, NASDAQ): country + region breakdowns from SEC 10-K XBRL dimensional facts. Currency USD, in millions. Mappable countries (``countries``) come back with ISO alpha-2 codes — these are what the frontend's revenue map colours. Regions (``regions``) carry their own grouping label (e.g. "EMEA", "Asia Pacific", "North America") and are *not* expanded into countries server-side — the caller decides how to combine them with country-level figures (some filers report both, in which case summing them would double-count). For analytical work, prefer country-level rows when available. The ``other`` bucket holds the company's catch-all "other countries" aggregate (e.g. ``aapl:OtherCountriesMember``). It can be sizeable (40%+ for filers that disclose only the top 1-2 countries) but is never broken down further. Args: company: Company name, ticker, or CIK. Examples: "Apple", "AAPL", "0000320193", "Neste", "Microsoft", "MSFT". Fuzzy matching is supported. year: Fiscal year to query (e.g. 2024). Default: most recent available annual filing. Returns: { "company_name": "Apple Inc.", "company_id": "aapl", "market": "us", "year": 2025, "currency": "USD", "unit": "milj_usd", # values are millions of currency "total_revenue": 416161.0, "total_revenue_mappable": 216167.0, "countries": [ {"name": "United States", "iso_alpha2": "US", "revenue": 151790.0, "page_id": "0000320193-25-000079"}, ... ], "regions": [ {"name": "Asia Pacific", "entity_type": "multi_region", "revenue": 67680.0, "page_id": "..."} ], "other": [ {"name": "Other countries (US filing)", "entity_type": "other", "revenue": 199994.0, "page_id": "0000320193-25-000079"} ], "additive_layer": "country+other", "total_revenue_reconciliation": { "group_revenue": 416161.0, "coverage_of_group_revenue": 1.0 } } **``total_revenue`` is one layer, never the sum of all rows.** Filers disclose geography at several granularities at once and those layers overlap by construction (an "Europe" row and a "Finland" row describe the same euros). ``additive_layer`` names the layer used; ``total_revenue_reconciliation`` shows the consolidated group revenue for the same period and what share of it the rows cover. A coverage below 1.0 is normal — most filers break out only part of their revenue by geography. ``overlap_warning`` explains any layer that was excluded (per-segment rows, parent-company rows, duplicate extractions). Returns ``{"error": "...", "company": "..."}`` when the company cannot be resolved or has no revenue-by-geography data on file.

get_revenue_geography

Return a curated peer set for a sector/country workflow. 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

Stock price for a listed company — latest close or historical series. **Mode selection (automatic):** - ``days=0`` and no ``start_date``/``end_date`` (default) → the most recent completed-session closing price, looked up via web search (~15 min delay). Every result carries freshness metadata: ``freshness_status`` (``live`` / ``recent`` / ``stale``), ``is_usable_for_live_quote``, ``age_seconds`` and ``age_trading_days``. The lookup is cached for ``prefer_cache_seconds``; pass ``force_refresh=true`` to bypass. Pass ``require_live=true`` when the user explicitly asks for a live price — if the best observation is stale, the call fails with ``failure_kind="stale_price"`` and ``best_observation``. - ``days>0`` or ``start_date``/``end_date`` given → historical daily closing prices from Clarifo's internal database (delayed T-1, up to 5 years / 1825 days). Use ISO ``start_date`` / ``end_date`` (YYYY-MM-DD) for an exact window, or ``days=N`` for a trailing lookback. When ``start_date``/``end_date`` are given they take precedence over ``days``. Returns a ``series`` of ``{date, close, volume}`` plus ``summary`` with total_return_pct, period high/low, and ``significant_moves`` (>=5% single-day changes). **Rendering**: always render as an interactive line chart (x=date, y=close). At least one of ``ticker`` or ``company_name`` must be supplied. **Follow-up "what happened here?"** (history mode): when the user points at a date range on the chart, gather context by calling ``company_events``, ``search_filings``, ``search_filing_content``, ``get_ceo_barometer`` for that window. Combine with the price move to explain causality. Returns (latest mode): ``{ticker, company_id, price, currency, share_class, trading_date, price_type, fetched_at, source, confidence, cache_hit, freshness_status, ...}``. Returns (history mode): ``{company, ticker, currency, data_points, period, summary, series}``. On 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. On error: ``{"error": "...", "failure_kind": "..."}``.

get_valuation_history

Read the full content of a single item from your own workspace. Only your own workspace is accessible (user taken from the authenticated MCP session, ownership 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 / not owned: {"error": "..."}.

get_workspace_item

DEF 14A proxy data for US companies — board, NEO pay, CEO pay ratio, say-on-pay. Three modes: - **snapshot** (default): single proxy for one company (latest or pinned to ``fiscal_year``). Use for "what does Apple's CEO earn?", "is NVIDIA's board independent?". - **trend**: multi-year board-composition and pay trend for one company in a single call. Use for "how has NVIDIA's board changed over time?", "how has the CEO pay ratio developed?". - **peer**: rank a peer set on a single governance metric. Use for "compare CEO pay ratio across Big Tech", "S&P 500 banks by board independence". Args: mode: ``"snapshot"`` (default), ``"trend"``, or ``"peer"``. company: Company name, ticker, or CIK. Required for snapshot and trend modes. companies: Peer set (2+ identifiers). Required for peer mode. fiscal_year: Pin to a specific fiscal year (snapshot and peer modes). Omit for the most recent proxy. years: Trend mode — cap on rows returned (newest-first, max 25, default 8). from_year: Trend mode — lower bound on fiscal year. to_year: Trend mode — upper bound on fiscal year. metric: Peer mode — ``"ceo_pay_ratio"`` (default), ``"ceo_total_pay"``, ``"board_independence"``, ``"female_director_ratio"``, ``"median_employee_pay"``, ``"sop_percent_for"``. direction: Peer mode — ``"desc"`` (default) or ``"asc"``. Returns: **Snapshot:** ``{company_name, ticker, cik, proxy: {fiscal_year, filing_date, board, executive_compensation, insider_ownership, say_on_pay, ceo_pay_ratio, source_url}}``. **Trend:** ``{company_name, ticker, cik, trend: [{fiscal_year, board_size, independent_ratio, ceo_total_pay_usd, ceo_pay_ratio, ...}]}``. **Peer:** ``{metric, direction, peers: [{company_name, ticker, value, proxy}], companies_not_resolved, coverage, missing}``.

governance

SEC Form 4 insider trading for a US company. Three modes: - **summary** (default): aggregate counts and net USD by reporter class (C-level vs 10%-owner) and transaction type. Pass ``granularity`` (``"quarter"`` or ``"month"``) for a per-period trend instead. Use for "is the CEO buying?", "net insider flow last quarter?", "insider purchases over the 2020s?". - **clusters**: detect cluster trades — multiple distinct C-level insiders trading the same direction inside a rolling window (Cohen-Malloy-Pomorski conviction signal). Ranked by conviction score. Use for "any coordinated insider buying at Apple?". - **transactions**: raw Form 4 rows newest-first. Use for "every Elon Musk Form 4 in 2026". Args: company: Company name, ticker, or CIK. mode: ``"summary"`` (default), ``"clusters"``, or ``"transactions"``. since_date: YYYY-MM-DD lower bound (default: last 365 days). until_date: YYYY-MM-DD upper bound. include_derivatives: Include option grants/exercises (default ``False``). Used in summary and transactions modes. granularity: Summary mode only — ``"quarter"`` or ``"month"`` to get a per-period trend instead of aggregate. periods: Summary trend mode only — cap on trend buckets (newest-first, max 60). direction: Clusters mode only — ``"purchase"`` (default) or ``"sale"``. window_days: Clusters mode only — rolling window in calendar days (1-365, default 90). min_insiders: Clusters mode only — minimum distinct C-level insiders (default 2, must be >=2). min_total_value: Clusters mode only — USD threshold. top_k: Clusters mode only — cap on returned clusters after dedup + ranking (default 5; 0 = all maximal clusters). include_raw: Clusters mode only — include pre-dedup candidate windows (audit use only). transaction_types: Transactions mode only — subset of ``["purchase", "sale", "award", "exercise", "other"]``. reporter_class: Transactions mode only — ``"officer"`` / ``"director"`` / ``"ten_pct_owner"`` / ``"c_level"``. reporter_cik: Transactions mode only — pin to a single insider. limit: Transactions mode only — row cap (default 50, max 1000). Returns: **Summary (aggregate):** ``{company_name, ticker, cik, summary: {transaction_count, net_value_usd, by_type, by_reporter_class}}``. **Summary (trend):** ``{company_name, ticker, cik, granularity, trend[]}``. **Clusters:** ``{company_name, ticker, cik, direction, window_days, clusters[]}`` conviction-ranked. **Transactions:** ``{company_name, ticker, cik, transactions[]}`` newest-first with 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. Only your own workspace is accessible — 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. 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 image of a result you already fetched. Call this tool **only when the user explicitly requests a chart, visualization, or graph**, or when the data clearly benefits from a visual representation (a multi-year trend, a peer ranking, a sensitivity heatmap). Do not call it by default — write your analysis first, and add a chart only when it earns its place. A single figure, a two-row comparison, or a result you already described in prose does not need a chart. Skipping this tool is the normal outcome. 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 the filings — never pass figures yourself, there is no parameter for them. Chartable tools: ``compare_companies``, ``forecast_financials``, ``get_company_financials``, ``get_institutional_ownership``, ``get_manager_portfolio``, ``get_position_history``, ``get_revenue_geography``, ``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. Returns: A one-line description plus the chart as a PNG image block; show the image inline. The chart data is also in ``structuredContent`` — do not read it out, the user already sees the chart.

render_chart

Analyse how an in-flight IASB/EFRAG reporting project affects companies. Three modes in one tool: - **assess** (default): per-company impact assessment grounded in filings. Returns scope assessment, baseline evidence with graded verification states, gap assessment, and unresolved questions. Use for "how would IFRS 20 affect Neste?", "DRM impact on Nordea?". Omit ``company`` to get the project card + evidence- checklist definition only. - **screen**: graded exposure screening across a company universe. Returns per-company classification (likely_relevant / potentially_relevant / no_public_evidence_found / likely_not_ relevant / not_assessable). Use for "which Finnish companies may be affected by IFRS 20?", "ESRS-40a exposure in Swedish banks?". - **card**: composed article-ready roadmap card (eight sections: What changed, Why it matters, Who may be affected, What to check now, Company filing example, What happens next, Primary sources, Confidence). Also carries ``visual_cards_outline``. Use for "IFRS 20 reporting change card". Known projects: "Risk Mitigation Accounting" (aka DRM), "IAS 28 Fair Value Option Amendments", "IFRS 20" (rate-regulated activities), "ESRS-40a" (ESRS for non-EU groups). Passing an unknown project returns the valid list. All modes are deterministic — no LLM spend. Args: project: Project name, id or alias — e.g. "IFRS 20", "DRM", "ias28-fair-value-option", "ESRS-40a". mode: ``"assess"`` (default), ``"screen"``, or ``"card"``. company: Company name or ticker (fuzzy-resolved). Used in ``assess`` mode (impact target) and ``card`` mode (filing example). Ignored in ``screen`` mode. companies: Explicit company list (max 15, fuzzy-resolved). Used in ``screen`` mode (universe) and ``card`` mode (Who may be affected). Ignored in ``assess``. industry: Industry filter for ``screen`` / ``card`` (e.g. "banking", "energy"). Ignored when ``companies`` is given. country: Country filter ("FI", "SE", ...) for ``screen`` / ``card``. Ignored when ``companies`` is given. top_n: Universe size for ``screen`` / ``card`` when ``companies`` is omitted (default 10, max 15). assess_depth: ``"full"`` (default — evidence + gap assessment) or ``"scoping"`` (scope signals only, cheaper). Only used in ``assess`` mode. as_of: Optional assessment date (echoed in assess output). Returns: **Assess mode:** ``{project, scope_assessment, baseline_evidence, gap_assessment, unresolved_questions, official_sources, filing_sources, source_policy, publication_gate}``. **Screen mode:** ``{project, companies (sorted most-relevant first, each with classification + confidence + reasons + evidence), methodology_audit, official_sources, source_policy}``. **Card mode:** ``{project, card (eight sections), visual_cards_outline, source_policy}``. Cite ``filing_sources[].citation_markdown`` / ``evidence[]. citation_markdown`` verbatim — never raw ``page_id`` strings.

reporting_change

Comprehensive company research combining financials, filing content, and analytical profile in a single call. This is the recommended starting point for company-level questions. Instead of calling search_filing_content, get_company_financials, and get_company_profile separately, this tool runs them in parallel and returns a unified result. **What it does:** 1. Resolves the company name (fuzzy matching, ticker support) 2. Fetches structured financial data (revenue, margins, growth) 3. Searches filing text for each topic (MD&A, Risk Factors, guidance) 4. Retrieves the analytical profile if available **When to use this vs. individual tools:** - Use ``research_company`` when you need a broad understanding of a company — "tell me about D.R. Horton", "why did KB Home's revenue decline?", "what are Nokia's key risks?" - Use individual tools when you need a specific, narrow piece of data (e.g. just the balance sheet, just one filing's text). **Date semantics in the response:** - ``period_end`` is the calendar date the period closes (e.g. ``2025-09-27`` for Apple's FY2025). - ``year`` always means the *fiscal* year that closes at ``period_end`` — never the filing date or the calendar year. - ``period_label`` is the human-readable form ("FY2025", "Q3/2025"). Args: company: Company name or ticker. Fuzzy matching supported. Examples: "D.R. Horton", "DHI", "KB Home", "Neste", "Nokia" topics: List of topics to search in filing text (max 5). Defaults to the first three entries of the shared filing-topic vocabulary (``backend/search/analysis_facets``): revenue trajectory, risks, outlook. Examples: ["mortgage rates impact", "inventory levels", "order backlog trends"] year: Restrict filing content search to a specific *fiscal* year. years: Number of annual periods for financial data (default 3, max 5). concise: When ``True``, return a slimmed-down payload — top 1 hit per topic (instead of 3), 220-char content snippets (instead of 800), and the profile is reduced to its ``overview`` + ``risks`` previews only. Roughly 70% smaller token footprint. Use in agentic workflows where the model only needs to know the shape of what the company does before deciding whether to drill in. Returns: { "company": { "name": "HORTON D R INC /DE/", "ticker": "DHI", "market": "us" }, "financials": { "by_year": {"2025": {...}, "2024": {...}}, "latest_period": {...}, "data_quality_warnings": [...] }, "filing_content": { "revenue development, growth, earnings trajectory, profitability": [ {"content": "...", "content_title": "Item 7 - MD&A", ...} ], "risks and uncertainties, risk factors, near-term risks": [...] }, "profile": { "overview": "...", "risks": "..." }, "sources": ["10-K FY2025", "10-Q Q1/2026", "XBRL financial data"] } ``financials`` carries the same integrity fields the standalone ``get_company_financials`` returns, so a figure quoted from here is exactly the figure that tool would give: - ``data_quality_warnings`` — a PDF-extracted figure that conflicts with the consolidated filing fact, or a metric the two internal pipelines disagreed on and which side won. Present only when something was actually flagged or corrected. - ``latest_period.metrics_available: false`` — the period resolved but has no structured figures ingested yet; ``superseded_period`` names it when an older period with real figures was used instead.

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 Nordic industrials called repeatedly — costs effectively zero on the second invocation. Args: companies: List of inputs to resolve. 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 on the six CEO-Barometer themes right now, without waiting for the always-on batch refresh. Returns the fresh −100…+100 sentiment index, per-theme scores with verbatim quotes and chunk-verified citations, plus the resolved reporting period. The tool does NOT persist the result — the CEO-Barometer snapshot table is written by the batch refresh cron only, so `get_ceo_barometer` will reflect the new number on its next scheduled run. Use this tool when a reader wants the live read for a specific company between refreshes, or when validating a freshly published CEO review before the batch job picks it up. Args: company: Canonical company name as used in Weaviate (usually the lowercase legal shortname, e.g. ``"kesko"``, ``"neste"``, ``"nokia"``). Not a ticker. year: Optional reporting-period year. Omit to score the freshest period the company has published. quarter: Optional reporting period quarter (1=Q1 / 2=H1 / 3=Q3 / 4=FY). Only used when ``year`` is set. language: ``"fi"`` (default) or ``"en"`` — controls both the LLM rubric language and the citation formatting. Returns: ``{company_name, official_name, period_end, period_type, index, tone, dominant_theme, themes, document_id, model}`` on success. ``{"error": "...", "available_periods": [...]}`` when the company has no CEO-review chunks for the requested period (Weaviate returns no rows, or the chunk metadata is stale). Pro-plan only: this tool runs Clarifo's own LLM against your query, so the spend is billed to us, not to your host. Free / trial / Plus subscribers get an upgrade pointer instead.

score_ceo_sentiment_for_company

Rank or screen the company universe by a financial metric. Use this for cross-company questions ("which Finnish companies grew revenue most in 2024?", "top 20 Swedish companies by EBITDA"). For single-company detail use ``get_financial_statement`` or ``get_company_financials`` instead. **Rendering:** this result is chartable but nothing draws it automatically. When the ranking is worth showing as a bar chart, follow up with ``render_chart(source_tool="screen_companies", source_args=...)`` passing the same arguments. A short list you are about to summarise in a sentence does not need one — present the ranked results as a formatted table instead. **Coverage notes:** - Main list (HEL + STO): ~190 companies with annual data. Includes First North companies in pre-aggregated metrics (revenue, EBIT, EBITDA, net_income, marketcap) but NOT in detailed ESEF/iXBRL line items (esef_facts). For First North companies, use ``screen_companies`` for screening and ``search_filing_content`` for filing detail. - US (NYSE + NASDAQ): ~1400 companies from SEC EDGAR 10-K filings. - ``compare_years > 3`` may return fewer results for Nordic data where older filings have not been ingested. **Growth mode and negative values:** When one or both of the anchor/compare values are negative (e.g. a loss-making company), ``growth_pct`` is set to ``null`` and the response includes ``trend`` ("deteriorating", "improving", "turned_positive", "turned_negative") and ``delta_absolute`` instead. This prevents misleading percentage values like "+303 %" for deepening losses. Args: metric: Metric to rank by. The skill picks the right backend automatically: - Pre-aggregated Nordic metrics (fastest): ``"revenue"``, ``"gross_profit"``, ``"ebit"``, ``"ebitda"``, ``"net_income"``, ``"operating_cash_flow"``, ``"free_cash_flow"``, ``"marketcap"``, ``"personnel"``, ``"eps_diluted"``, ``"shares_outstanding"``. - Granular IFRS line items (Nordic ``esef_facts``): ``"cost_of_sales"``, ``"operating_profit"``, ``"profit_before_tax"``, ``"income_tax_expense"``, ``"research_and_development_expense"``, ``"selling_and_marketing_expense"``, ``"administrative_expense"``, ``"finance_costs"``, ``"finance_income"``, ``"total_assets"``, ``"current_assets"``, ``"non_current_assets"``, ``"total_equity"``, ``"equity_attributable_to_owners"``, ``"total_liabilities"``, ``"current_liabilities"``, ``"non_current_liabilities"``, ``"cash_and_equivalents"``, ``"investing_cash_flow"``, ``"financing_cash_flow"``. - Filing-extracted KPIs (Nordic ``avainluvut``): ``"order_book"`` (tilauskanta), ``"order_intake"``, ``"equity_ratio"``, etc. - US (``USFinancialFacts``, US-GAAP tags): every metric listed above except ``ebit``, ``ebitda``, ``free_cash_flow``, ``marketcap``, ``personnel``, ``eps_diluted``, ``shares_outstanding``, ``order_book``, ``order_intake``, ``equity_ratio``. Coverage matches the Nordic ESEF backend so the same metric key works cross-market. - Derived margin metrics (Nordic + US): ``"gross_margin"``, ``"operating_margin"``, ``"ebit_margin"``, ``"net_margin"``, ``"net_profit_margin"``. Ratio (0.25 = 25 %), computed in SQL from the underlying numerator and revenue — no LLM math. - ``"ebitda_margin"``: Nordic via ``ebitda / revenue`` (keymetrics column); US via ``(operating_income + depreciation_amortization) / revenue`` — no canonical US-GAAP EBITDA tag exists, so the numerator is synthesised from the two reported components. Companies missing a standalone D&A tag are excluded from the US ranking — the screener never silently treats missing D&A as zero. - ``"ebitda"``: Nordic from keymetrics; US derived same as ``ebitda_margin`` numerator (``operating_income + depreciation_amortization``). - ``"fcf_margin"``: Nordic via ``free_cash_flow / revenue``; US via ``(operating_cash_flow − capex) / revenue``. Companies that did not file a capex line are excluded — the screener never silently treats missing capex as zero. mode: ``"growth"`` (default) ranks by year-over-year growth %. ``"value"`` ranks by the absolute metric value at ``year`` (largest first) — i.e. the level, not a growth figure. ``"level"`` is accepted as an alias for ``"value"`` for callers who read "value" as "valuation". year: Anchor year. Omit to use the latest fiscal year for which data exists for the requested ``metric`` and ``country`` — the skill resolves this from the underlying tables at call time, so the default tracks the data automatically as new filings land. compare_years: For growth mode only — how many years back to compare against. ``1`` = YoY (default), ``4`` = growth from 4 years ago to ``year``. country: Scope. Pass ``"Nordic"`` (also accepts ``"Nordics"`` / ``"Scandinavia"``) to screen every Helsinki + Stockholm issuer in one call — do NOT call twice with ``"FI"`` and ``"SE"`` and merge the results yourself, the ``"Nordic"`` scope already runs the Nordic backend across both exchanges in a single pass and returns them pre-merged and pre-ranked. Other values: ``"FI"`` (Helsinki only), ``"SE"`` (Stockholm only), ``"US"`` (NYSE + NASDAQ). Omit to scan both markets (Nordic + US) concurrently. Note: ``"value"`` mode with country=None mixes EUR + SEK + USD; use the per-row ``currency`` field or the ``value_anchor_eur`` / ``value_compare_eur`` fields for cross-currency comparison. industry: Free-text substring match on ``companies.industry`` (e.g. ``"construction"``, ``"techn"``). Imprecise — use ``tag_slugs`` when you know the taxonomy. tag_slugs: Precise sector / theme filter via the ``company_tags`` taxonomy. Example: ``["construction", "real-estate"]``. top_n: Number of companies to return (1–100, default 20). direction: ``"desc"`` (largest first, default) or ``"asc"``. min_value: Optional minimum ``value_anchor`` to filter out micro-caps when ranking by absolute value. Operates on native currency — use together with ``country`` to avoid cross-currency mismatches. include_types: Filter by entity type. List of one or more of: ``"operating"``, ``"holding"``, ``"reit"``, ``"bank"``, ``"investment_vehicle"``. Omit (default) to return all entity types. Recommended: ``["operating"]`` for revenue/EBIT growth screens to exclude investment vehicles, holding companies, REITs and banks whose "revenue growth" has different semantics. index: Restrict the universe to a market index. Currently supported: ``"sp500"`` (also accepts ``"s&p 500"``, ``"s&p500"``) — backed by ``USCompanies.is_sp500``. When set, ``country`` is forced to ``"US"`` because the supported indices are US-only. Combine with ``industry="technology"`` / ``tag_slugs=["technology"]`` + a derived margin metric (``fcf_margin``) to answer questions like "list S&P 500 software companies with FCF margin above 25 %". Returns: { "metric": "revenue", "mode": "growth", "year": 2024, "compare_year": 2023, "filters": {"country": "FI", "industry": null, "tag_slugs": null}, "companies": [ {"company_name": "fiskars", "display_name": "Fiskars Oyj Abp", "ticker": "FSKRS.HE", "country": "FI", "industry": "...", "entity_type": "operating", "market": "nordic", "currency": "EUR", "value_anchor": 1320.0, "value_compare": 1250.0, "growth_pct": 5.6, "delta_absolute": 70.0, "trend": "growing", "signs_consistent": true, "value_anchor_eur": 1320.0, "value_compare_eur": 1250.0} ], "coverage": {"total_in_scope": 152, "with_data": 47, "returned": 20} } ``coverage`` distinguishes three counts so "how many passed the query" is never confused with "how many companies exist for this year": - ``total_in_scope``: companies the backend covers for ``year`` at all, after the country/industry/tag filters — the denominator. - ``with_data``: of those, how many reported *this* metric (a value for ``year``). Use ``with_data / total_in_scope`` to judge coverage, e.g. whether a more recent year is too sparse to screen on a comparable basis. - ``returned``: rows in ``companies`` after share-class deduplication, ``include_types`` filtering and the ``top_n`` limit. When fewer than 20 % of in-scope companies reported the metric (``with_data / total_in_scope < 0.20``) the response also carries a top-level ``coverage_warning`` string, e.g.:: "coverage_warning": "Low data coverage: only 8% of in-scope companies (15/178) reported ebit_margin. Results may not be representative." Treat its presence as a signal that the ranking is drawn from a thin slice and may not be representative of the full universe. **Data-quality guard.** In ``growth`` mode, a company whose anchor and compare figures cannot be on the same scale — a ≥ 100x swing on an absolute monetary metric, or a change of reporting currency between the two years — is withheld from the ranking and reported instead under ``excluded_data_quality``, alongside a top-level ``data_quality_warning`` string. Such a figure is a units slip or a statement-scope error in the underlying filing extraction, not a result; left in the ranking it lands at rank 1 and crowds out every genuine name. The withheld rows are always shown, never silently dropped, so the exclusion can be audited:: "excluded_data_quality": [ {"company_name": "...", "value_anchor": 1.91e10, "value_compare": 4195000.0, "growth_pct": 455214.2, "data_quality_warnings": [ {"type": "implausible_year_over_year_scale", "severity": "high", "ratio": 4553.0, "message": "..."}]} ] Ratio metrics (margins, multiples, per-share counts) are exempt — they legitimately swing by orders of magnitude around zero. On invalid input: ``{"error": "..."}``.

screen_companies

Screen companies by multiple financial criteria in a single call. Each filter specifies a metric and a constraint (growth range or value range). Only companies passing ALL filters are returned. This replaces the pattern of calling ``screen_companies`` multiple times and manually joining by company name. Args: filters: List of filter objects. Each has: - ``metric`` (required): metric name (same as screen_companies). - ``mode``: ``"growth"`` (default) or ``"value"``. - ``growth_min``: minimum growth % (growth mode only). - ``growth_max``: maximum growth % (growth mode only). - ``value_min``: minimum absolute value. - ``value_max``: maximum absolute value. - ``compare_years``: years back for growth (default 1). Example: ``[ {"metric": "revenue", "mode": "growth", "growth_min": 15}, {"metric": "ebit", "mode": "value", "value_min": 0}, {"metric": "marketcap", "mode": "value", "value_max": 500000000} ]`` country: Scope. Pass ``"Nordic"`` (also accepts ``"Nordics"`` / ``"Scandinavia"``) to screen every Helsinki + Stockholm issuer in one call — do NOT call twice with ``"FI"`` and ``"SE"`` and merge the results yourself, the ``"Nordic"`` scope already runs the Nordic backend across both exchanges in a single pass. Other values: ``"FI"`` (Helsinki only), ``"SE"`` (Stockholm only), ``"US"`` (NYSE + NASDAQ). Omit for all markets. include_types: Entity type filter (``["operating"]`` recommended). top_n: Max companies to return (default 20). rank_by: Index into ``filters`` to use as the ranking metric (default 0 = first filter). index: Restrict the universe to a market index (e.g. ``"sp500"``). When set, ``country`` is forced to ``"US"``. See ``screen_companies`` for supported indices. Returns: { "filters_applied": [...], "companies": [...], "coverage": {"passed_all": 15, "returned": 15} }

screen_companies_multi

Build a multi-period time series for one financial metric across a peer group — the "is it cheap/expanding vs. its peers and its own history?" chart, with every cell traceable to one filing period. **Rendering:** this result is chartable but nothing draws it automatically. A peer trend across periods is usually clearer as a chart — follow up with ``render_chart(source_tool="screen_metric_trend", source_args=...)`` passing the same arguments. Otherwise present ``series_data`` as a formatted peer-comparison table with periods as columns. Two ways to choose the companies: - **Explicit peers**: pass ``peers=["Costco", "Walmart", "Target"]`` (names or tickers, Nordic and/or US, mixed is fine). - **Ranked group**: omit ``peers`` and the tool ranks the top ``top_n`` companies by ``rank_metric`` (defaults to ``metric``), filtered by ``countries`` / ``industry`` / ``tag_slugs``. Margins (``gross_margin``, ``operating_margin``, ``ebit_margin``, ``ebitda_margin``, ``net_margin``) are computed deterministically from the underlying numerator/revenue pair — no LLM arithmetic. ``ebit_margin`` pins to a true EBIT figure (keymetrics ``ebit`` / US-GAAP ``operating_income``) and is distinct from ``operating_margin``, which uses the IFRS ``operating_profit`` line on the ESEF backend. The output is shaped for a chart: see ``chart_series`` and ``series_data``. Args: metric: Metric to trend. Pre-aggregated Nordic + US: ``"revenue"``, ``"gross_profit"``, ``"ebit"``, ``"ebitda"``, ``"net_income"``, ``"operating_cash_flow"``, ``"free_cash_flow"``; margins as above; plus granular ESEF line items (annual only) and US-GAAP tags. ``ebitda`` / ``ebitda_margin`` are Nordic-only (no canonical US-GAAP EBITDA tag). peers: Explicit company list (names or tickers). When given, ranking filters are ignored. countries: Restrict the ranked universe to ``["FI"]``, ``["SE"]``, ``["DK"]``, ``["US"]`` or a combination. Omit to scan all covered markets. industry: Free-text substring match on the company's industry. tag_slugs: Precise sector/theme taxonomy filter. top_n: Ranked-mode peer-group size (1–25, default 8). Ignored when ``peers`` is given. window: Number of periods in the series (2–20, default 5). anchor_year: Most-recent period to anchor on. Omit for the latest available. frequency: ``"annual"`` (default) or ``"quarterly"``. Quarterly is supported on the Nordic keymetrics backend only; pairing it with an ESEF-only metric or ``countries=["US"]`` returns an explicit error. rank_metric: Metric used to pick the ranked peer group (defaults to ``metric``). Ignored when ``peers`` is given. strict_resolution: In explicit-peer mode, fail closed on cross-market ties or ambiguous matches instead of silently choosing. Returns: The skill's payload: ``{metric, metric_label, unit, frequency, anchor_period, periods, companies, series_data, chart_series, coverage, backends_used}``. On invalid input: ``{"error": "..."}``.

screen_metric_trend

Screen for quality growth companies — revenue CAGR + positive and improving EBIT + positive operating cash flow, excluding non-operating entity types. This is a composite screen equivalent to calling ``screen_companies`` 3–4 times and intersecting manually. Inspired by Fundsmith / Terry Smith style quality-growth investing. **Rendering:** this result is chartable but nothing draws it automatically. When a bar chart of the ranking adds something, follow up with ``render_chart(source_tool="screen_quality_growers", source_args=...)`` passing the same arguments. Otherwise present the companies as a ranked table showing the quality metrics. A company must pass ALL criteria: 1. Revenue CAGR over ``compare_years`` ≥ ``min_revenue_cagr`` 2. EBIT positive in the anchor year 3. EBIT margin improving (anchor > compare period) 4. Operating cash flow positive in the anchor year 5. Entity type is ``"operating"`` (no investment vehicles / REITs / banks) Args: country: Scope. Pass ``"Nordic"`` to screen every Helsinki + Stockholm issuer in one call — do NOT call twice with ``"FI"`` and ``"SE"`` and merge the results yourself, the ``"Nordic"`` scope already runs the Nordic backend across both exchanges in a single pass and returns them pre-merged and pre-ranked. Also accepts ``"Nordics"`` / ``"Scandinavia"`` as aliases for the same scope. Other values: ``"FI"`` (Helsinki only), ``"SE"`` (Stockholm only), ``"US"`` (NYSE + NASDAQ). Omit to screen all markets (Nordic + US) concurrently. min_revenue_cagr: Minimum revenue CAGR % (default 10). compare_years: Look-back window in years (default 3). max_marketcap: Optional upper bound on market cap (native currency). top_n: Max results to return (default 20). Returns: { "quality_criteria": { ... }, "companies": [ { "company_name": "...", "quality_metrics": { "revenue_cagr_pct": 18.5, "ebit_anchor": 12000000, "ebit_margin_anchor_pct": 8.2, "ebit_margin_compare_pct": 6.1, "operating_cash_flow_anchor": 15000000 }, ... } ], "coverage": { "passed_quality_filter": 12, "returned": 12 } }

screen_quality_growers

Semantic search within the full text of company filings (annual reports, interim reports, stock exchange releases, SEC filings). This tool finds passages relevant to the query using vector similarity — great for qualitative questions, strategy, risk factors, guidance, etc. Searches both Nordic (HEL, STO) and US (NYSE, NASDAQ) filings. **Company name resolution:** The tool automatically resolves brand names and tickers to canonical database names (e.g. "D.R. Horton" → "HORTON D R INC /DE/", "DHI" → same). You do not need to know the exact database name. **Entity detection:** If you mention a company name in the query text without setting the ``company`` parameter, the tool will try to detect it and suggest using the ``company`` parameter for better results. **Important:** This is a semantic (vector) search. Results are ranked by meaning similarity, not exact keyword match. A high score means the passage is semantically related to your query — always verify that the returned company_name matches the company you asked about. Recall improves when the query itself carries synonyms and, for Nordic filings, both English and local-language terms (e.g. "impairment goodwill arvonalentuminen liikearvo") — you are the query rewriter. **Tag filters (deterministic, no LLM):** filings are indexed with a controlled tag vocabulary. Passing ``topic_tags`` / ``ifrs_tags`` restricts results to pages actually tagged with those concepts — far more precise than vector similarity alone for accounting-policy and disclosure questions. If you pass neither, the server auto-detects tags from the query text using the same synonym tables the indexer used and reports what it applied in the response's ``tag_filters`` block (disable with ``auto_detect_tags=False``). A tag filter that matches nothing is automatically retried without tags (``tag_filters.applied: false``), so tags can only help recall, never silently zero it. **Citing sources to the user:** every result carries a ready-made ``citation_label`` and ``citation_markdown`` (a human-readable label linked to ``source_url``). Print those verbatim when citing. ``page_id`` is Clarifo's internal anchor for follow-up tool calls (``get_filing_snapshot``, ``clarifo://filing/{page_id}``) — never show a raw ``page_id`` string in user-facing text. Args: query: Natural language search query. Examples: - "Neste renewable diesel production capacity 2023" - "Nokia 5G risk factors" - "Apple dividend policy" - "D.R. Horton revenue decline mortgage rates" company: Optionally restrict to a specific company (name or ticker). Fuzzy matching supported: "D.R. Horton", "DHI", "KB Home" all work. year: Optionally restrict to a specific year. quarter: Optionally restrict to a fiscal quarter (1-4). Note that the quarter field is unpopulated for part of the corpus, so a quarter filter can exclude relevant pages — prefer it only when the question is explicitly about one quarter's interim report. document_type: Optionally filter by logical type: "annual_report", "interim_report", "stock_exchange_release", "10-K", "10-Q", etc. Aliases are normalized server-side — "annual_report" also matches filings indexed as "financial_statement"/"10-K"/"20-F", and Nordic names like "tilinpäätös"/"årsredovisning" work. You do not need to know Clarifo's internal taxonomy. market: Limit search to a specific market: "nordic" or "us". Omit to auto-detect from the company name, or search Nordic by default for unscoped queries. limit: Number of passages to return (default 5, max 20). include_adjacent_pages: When true, also fetch the page before and after each Nordic hit from the same document (marked ``is_adjacent_page`` with ``supports: "context"``). Use for accounting-policy / disclosure questions where the policy text regularly starts on the previous page or continues on the next one. US filings are unaffected. index: Restrict the search to a market index. Currently only ``"sp500"`` is supported (US-only; auto-forces ``market="us"``). The constituent CIKs are resolved from ``USCompanies.is_sp500`` and each tenant is queried in parallel. Cannot be combined with ``company`` — use one or the other. Example: ``index="sp500"`` + ``query="AI risk factors"`` returns the top-N passages discussing AI risk across the S&P 500. topic_tags: Restrict to pages tagged with any of these topic tags (case-insensitive; unknown values are ignored and reported back). Vocabulary: audit report, balance_sheet, board, borrowings, business_combination, cash_and_cash_equivalents, cash_flow, ceo_review, closed, consolidation, cost_efficiency, customer_contracts, deferred_tax, dividends, earnings_per_share, employee_benefits, equity, fair_value_measurements, finances, financial_instruments, financial_results, goodwill, impairment, income_tax, intangible_assets, inventories, investment_property, investments, lawsuits, leases, leasing, market_environment, marketcap, opomuutos, ownership, personnel, profitloss, property_plant_and_equipment, provisions, related_party, revenuebycountry, risks_uncertainty, segment_performance, segment_reporting, share_based_payments, strategy, strategy_outlook, sustainability, sustboard, sustclimate, sustcoal, sustdiversity, sustdouble, susteu, sustframework, sustpeople, sustrisks, suststrategy, trade_payables, trade_receivables, transactionsafter, tunnusluvut. ifrs_tags: Restrict to pages tagged with any of these IFRS/IAS standards (Nordic filings only — US filings carry no IFRS tags, so the filter is skipped on US searches and reported in ``tag_filters``). Vocabulary: IAS 1, IAS 2, IAS 7, IAS 8, IAS 10, IAS 12, IAS 16, IAS 36, IAS 37, IAS 38, IAS 40, IFRS 1, IFRS 2, IFRS 3, IFRS 7, IFRS 8, IFRS 9, IFRS 10, IFRS 11, IFRS 12, IFRS 15, IFRS 16, IFRS 18. auto_detect_tags: When True (default) and no explicit tags were passed, tags are detected from the query text with the indexer's synonym tables and applied automatically. Set False for a pure vector search with no tag filtering. response_mode: ``"detailed"`` (default) or ``"concise"``. ``"detailed"`` returns the historical shape. ``"concise"`` drops the ~700-char ``evidence.excerpt`` (always a strict superset of ``content``), removes evidence sub-fields that already live at the top level, and slims each source row down to citation anchors — reducing broad multi-company searches from hundreds of thousands of tokens to a payload a model can actually reason over. Every top-level field (``citation_label``, ``citation_markdown``, ``source_url``, ``page_id``, ``page_number``, …) is retained, so a concise-mode caller can still print citations verbatim. Use ``"concise"`` whenever you plan to fan out across more than a couple of companies or documents. max_total_results: Optional hard cap applied AFTER the ``include_adjacent_pages`` expansion, so a ``limit=12`` + adjacent-page query cannot balloon to 24+ rows for the caller. Default is unset (no post-expansion cap); the per-hit primary limit is still ``limit``. Use to keep the payload deterministic when you turn adjacent pages on. Returns: { "results": [ { "content": "...", "page_id": "...", "page_number": 139, "evidence": { "company": "...", "document_title": "...", "period": "FY2025", "source_url": "...", "excerpt": "...", "evidence_type": "financial_statement_note", "supports": "direct", "confidence": "high" } } ], "sources": [{...}], "source_policy": { "citation_mode": "claim_level", "require_excerpt": true, "require_page_number": true, "require_source_url": true, "max_sources_per_claim": 3 }, "total": 5, "has_more": false, "query": "...", "resolution": { "input_company": "D.R. Horton", "resolved_name": "HORTON D R INC /DE/", "market": "us", "ticker": "DHI" }, "tag_filters": { "topic_tags": ["leases"], "ifrs_tags": ["IFRS 16"], "source": "auto_detected", # or "caller" "applied": true # false = matched nothing, results # come from an unfiltered retry } } When no content is found, includes a "diagnostic" field explaining why (company not resolved, content not indexed, etc.).

search_filing_content

Search for company filings (annual reports, interim reports, stock exchange releases). Returns a list of matching documents with company name, year, quarter, document type, and a docid you can use with search_filing_content. **Company name resolution:** Automatically resolves brand names and tickers to canonical database names. "D.R. Horton", "DHI", "KB Home" all work. Exact ticker matches are prioritized in results. **Date semantics in the response:** Each filing carries three independent date-shaped fields. They are not interchangeable, and any "this filing is from 2025" reasoning needs to start from the field that fits the question: - ``fiscal_year`` — the fiscal year the filing reports on. This is the canonical "year" for comparisons across companies. Apple's FY2025 closes 2025-09-27, Lennar's FY2025 closes 2025-11-30, D.R. Horton's FY2025 closes 2025-09-30. Always populated. - ``period_end`` — the actual calendar end date of the reporting period (ISO-8601). The only field safe to compare across companies on a literal calendar timeline. - ``filed_date`` — when the document was filed with the regulator. Useful for "what came out this week" questions, but the *contents* describe ``fiscal_year`` / ``period_end``, not ``filed_date``. - ``year`` (legacy) — alias of ``fiscal_year``. Always populated; the historical ``year: null`` case is treated as a data bug, not a valid response. The ``year_from`` / ``year_to`` filters operate on ``fiscal_year``. ``period_end`` / ``filed_date`` coverage: for US per-filing results (``result_kind: "filing"``) both are sourced from the real SEC filing index and populated whenever a confident (form_type, fiscal-year) match exists. For US company-level fallback rows (``result_kind: "company_index"`` — one row per issuer, not per filing) and for all Nordic rows, per-filing date metadata is not yet tracked; when either field can't be populated the filing carries a ``metadata_quality`` object instead of a silently-missing key, e.g. ``{"period_end": "missing"}`` (US, no confident match) or ``{"period_end": "not_tracked_for_nordic_filings", "filed_date": "not_tracked_for_nordic_filings"}`` (Nordic). Args: company: Company name or ticker symbol. Fuzzy matching supported. Examples: "Neste", "NESTE", "Nokia", "Apple", "AAPL", "D.R. Horton", "DHI", "KB Home" year_from: Earliest *fiscal* year to include (e.g. 2020). year_to: Latest *fiscal* year to include (e.g. 2024). document_type: Filter by document type. Options: "annual_report", "interim_report", "stock_exchange_release", "10-K", "10-Q", "8-K" (US SEC filings) market: Limit to a specific market: "nordic" (HEL, STO) or "us" (NYSE, NASDAQ). Exchange-style aliases are accepted and normalized ("HEL", "STO", "OMXH" -> nordic; "NYSE", "NASDAQ" -> us). An unrecognized value returns a validation error rather than silently matching nothing. Omit to search both markets. market="us" without a company lists filings across ALL US companies from the SEC filing index (newest filed first). limit: Maximum number of results per page (default 20, max 100) offset: Number of results to skip for pagination (default 0, max 1000). Combine with ``has_more`` / ``total_available`` to page through large slices deterministically (Nordic rows sort by fiscal year desc, quarter desc, company name; US broad rows sort by filed date desc). Returns: { "filings": [ { "company_name": "HORTON D R INC /DE/", "ticker": "DHI", "fiscal_year": 2025, "year": 2025, "period_end": "2025-09-30", "filed_date": "2025-11-12", "document_type": "10-K", "docid": "..." } ], "total": 5, # rows in THIS page (echo of len(filings)) "total_available": 512, # true match count before paging, when known "has_more": true, "offset": 0, "resolution": { "input_company": "D.R. Horton", "resolved_name": "HORTON D R INC /DE/", "market": "us", "ticker": "DHI" } }

search_filings

Keyword text search directly on filing tables (PostgreSQL). Reaches filings that ``search_filing_content`` (Weaviate semantic search) cannot: US filings 2015-2024 whose text has not been vectorized yet, and any year parsed faster than it is indexed. Also useful as a fast, deterministic path when you already know the company, year, and document type and don't need semantic recall. **When to use this instead of search_filing_content:** 1. You need historical US filings (2015-2024) and search_filing_content returned nothing. 2. You have a tightly scoped query (company + year + doctype) and want exact keyword matches, not semantic similarity. **When NOT to use this:** for cross-company discovery, broad topical searches, or when you don't know the company. Use search_filing_content for those. Results carry evidence-card ``sources`` with ``citation_markdown`` — cite those verbatim. ``page_id`` is an internal anchor for ``get_filing_snapshot``; never show it to the user. Args: company: Company name, ticker, or CIK (required). Examples: "Microsoft", "MSFT", "0000789019". query: Natural language question. Keywords are extracted and OR-combined via ILIKE. Up to 8 keywords used. year: Fiscal year filter (e.g. 2020). quarter: Quarter filter (1-4). When the quarter column is unpopulated (common in older filings), the search automatically retries including untagged rows and reports ``quarter_filter_relaxed: true``. document_type: Logical type or corpus spelling: "10-K", "10-Q", "annual_report", "interim_report", "20-F", etc. Aliases are expanded automatically ("annual_report" also matches "financial_statement"/"10-K"/"20-F"). market: "us" or "nordic". Auto-detected from the company if omitted. limit: Max rows (default 20, max 50). Returns: { "results": [{ "page_id": "...", "docid": "...", "year": 2016, "document_type": "10-K", "page_number": 42, "section_name": "Item 7. MD&A", "company_name": "MICROSOFT CORP", "content_excerpt": "Revenue for fiscal 2016 ...", "match_score": 3 }], "sources": [{"citation_markdown": "[...](...)", ...}], "source_policy": {...}, "total_matches": 17, "keywords_used": ["revenue", "cloud"], "quarter_filter_relaxed": false, "resolution": {"input_company": "...", "resolved_name": "...", ...} }

search_filings_sql

XBRL dimensional segment data for US companies — list, query, compare, or screen. Four modes: - **list**: which axes (business / product / geographic) and members a company reports. Call first when unsure what segments exist. Only needs ``company``. - **financials** (default): per-segment metric breakdown across multiple periods. Use for "NVIDIA Data Center revenue per quarter", "Apple iPhone vs Services split". - **compare**: side-by-side segment data for 2-5 companies on the same metric and period window. Use for "compare NVIDIA and AMD Data Center revenue". Pass ``member_filter`` (e.g. ``["Data Center"]``) to focus on specific segments. - **screen**: rank segment rows across a universe by value or growth. Use for "top 20 S&P 500 tech companies by Data Center segment revenue growth". Coverage: US filers only (SEC EDGAR XBRL via ``USFinancialFactDimensions``). Args: mode: ``"financials"`` (default), ``"list"``, ``"compare"``, or ``"screen"``. company: Company name or ticker. Required for ``list`` and ``financials`` modes. companies: 2-5 company names/tickers. Required for ``compare`` mode. Optional for ``screen`` (explicit universe). metric: ``"revenue"`` (default), ``"operating_income"``, ``"gross_profit"``, ``"assets"``, ``"depreciation_amortization"``. Used in financials, compare, and screen modes. axis: ``"business"`` (default), ``"product"``, ``"geographic"``, ``"consolidation"``, or a literal XBRL axis string. period_type: ``"quarterly"`` (default) or ``"annual"``. periods: Most-recent rows per (axis, member) group (default 8). Used in financials and compare modes. year: Pin to a specific fiscal year. quarter: Screen mode only — anchor quarter (1-4) for quarterly. compare_years: Screen mode (growth) only — how many years back (default 1 = YoY). screen_mode: Screen mode only — ``"value"`` (default) or ``"growth"`` (% change). member_filter: Substring list matched case-insensitively against both friendly label and raw XBRL member string. E.g. ``["Data Center"]``. Used in financials, compare and screen modes. In financials mode the lookup becomes axis-agnostic: the named line is found wherever the issuer tags it (NVIDIA's "Data Center" sits on the product axis, AMD's on the business-segment axis). industry: Screen mode only — industry keyword(s). include_types: Screen mode only — ``["operating", "bank", "reit", "holding", "investment_vehicle"]``. index: Screen mode only — ``"sp500"``. value_min / value_max: Screen mode only — USD value bounds. growth_min / growth_max: Screen mode (growth) only — % bounds. top_n: Screen mode only — max rows (1-100, default 20). direction: Screen mode only — ``"desc"`` (default) or ``"asc"``. Returns: **List:** ``{company_name, cik, axes[]}``. **Financials:** ``{company_name, cik, axis, metric, period_type, segments[]}``. **Compare:** ``{metric, axis, period_type, companies[], not_found, coverage_notes}``. **Screen:** ``{metric, axis, period_type, mode, anchor, compare, filters, rows[], coverage}``.

segment_analysis

Company valuation — from a quick multiples snapshot to a full DCF model. Four modes: - ``"forward_dcf"`` (default): intrinsic enterprise / equity / per-share value from projected free cash flow, with a WACC × growth sensitivity grid and a quality read. - ``"reverse_dcf"``: solve for the explicit-period FCF growth the **current market price** implies — "what's priced in?". Needs a price: pass ``current_share_price``, or leave it unset and the tool fetches the most recent completed close internally (same source as ``get_stock_price`` — previous session's close, not an intraday tick) so per-share upside and reverse DCF work end-to-end without manual price input. - ``"implied_expectations"``: **two-axis sensitivity grid** — for each (x, y) pair on the two chosen operating drivers, compute the DCF per-share value under otherwise-fixed assumptions. Answers "what has to be true operationally for today's price to make sense?" — e.g. revenue growth × operating margin, or revenue growth × FCF margin. Supported axes: ``revenue_cagr``, ``operating_margin``, ``fcf_margin``, ``terminal_growth``, ``wacc``, ``fcf_conversion``, ``tax_rate``. Axes and values default to a sensible ladder when omitted. Base values for the non-varied drivers are derived from the trailing-3y history (median operating margin, revenue CAGR, FCF/NOPAT conversion), overridable via ``base_*`` / ``fcf_conversion``. - ``"multiples"``: trailing valuation multiples (P/E, P/B, P/S, EV/EBITDA, EV/Sales, FCF yield) from a live price and the latest annual fundamentals. No modelling assumptions needed — use for "what's NVIDIA's P/E?", "is Apple expensive on an EV/EBITDA basis?". Only ``company`` and optionally ``market``, ``current_share_price``, ``shares_outstanding`` are used; all DCF parameters are ignored. Works for Nordic (HEL, STO; ESEF/iXBRL) and US (NYSE, NASDAQ; SEC EDGAR) companies. Free-cash-flow history (operating cash flow minus capex) and the latest balance sheet (debt, cash, equity) are pulled from filings; the math is deterministic. **Every assumption is yours to set.** Anything left ``None`` is derived from data (WACC via CAPM with a data-derived cost of debt and a sector-aware beta ladder, FCF growth via historical CAGR) and echoed back under ``assumptions`` and ``inputs`` for audit. **Sector applicability:** the response carries ``sector``, ``industry`` and ``sector_fit`` (``"ok"`` / ``"caution"`` / ``"unsuitable"``). For banks and insurers (``"unsuitable"``) an OCF-based DCF is conceptually wrong — present the result as illustrative only and relay the ``quality_notes`` explanation; a dividend-discount or excess-return model is the accepted approach for those companies. **Rendering:** every mode is chartable, but nothing draws it automatically. The sensitivity modes gain the most from it — follow up with ``render_chart(source_tool="value_company", source_args=...)`` passing the same arguments to draw ``implied_expectations`` as a heatmap the reader can explore for the (growth, margin) pairs that justify the current price, ``forward_dcf`` as a WACC x growth heatmap, or ``reverse_dcf`` / ``multiples`` as KPI tables. Otherwise present ``sensitivity_grid.cells`` as a formatted table and highlight the contour where ``implied_upside`` crosses zero. **Coverage note on per-share value:** unless ``current_share_price`` is passed, the price is always fetched live (most recent completed close, Nordic and US alike); the Nordic ``keymetrics``-implied price is only a fallback when the fetch fails, and ``price.source`` / ``quality_notes`` say which one was used. Nordic shares come from ``keymetrics``; US shares are derived from ``net_income / diluted_eps``. When the share count is unknown, only enterprise and equity value are returned and ``quality_notes`` says so — the tool never invents a price. Args: company: Company name or ticker (e.g. "Fiskars", "Neste", "AAPL"). mode: ``"forward_dcf"`` (default), ``"reverse_dcf"``, ``"implied_expectations"``, or ``"multiples"``. market: Restrict to ``"nordic"`` or ``"us"``. Omit to auto-detect. wacc: Discount rate as a fraction (e.g. ``0.09``). Default: CAPM. fcf_growth: Explicit-period FCF growth as a fraction (e.g. ``0.06``). Default: historical CAGR. Ignored in reverse mode. terminal_growth: Perpetuity growth as a fraction (default ``0.025``). forecast_years: Explicit forecast horizon (3–15, default 5). fade_years: Convergence phase after the explicit period — growth fades linearly from the explicit rate to ``terminal_growth`` over this many years before the perpetuity (0–15, default 5; the conventional explicit + fade + terminal structure). ``0`` reproduces the plain two-stage model. use_forecast: Forward mode only — project the explicit-period FCF from a log-linear regression of the full FCF history (smooths a noisy base year) instead of compounding the latest FCF at its historical CAGR. Needs ≥3 strictly positive FCF years; degrades to the CAGR path with a note. solve_for: Reverse mode only — ``"growth"`` (default) solves the FCF growth the price implies at a fixed WACC; ``"wacc"`` solves the discount rate the price implies at a fixed growth path (``reverse.implied_wacc``). beta: Equity beta for CAPM. Default: the stored company beta, else a GICS sector-default beta, else market beta 1.0. risk_free_rate: Risk-free rate fraction (default ``0.035``). equity_risk_premium: ERP fraction (default ``0.055``). tax_rate: Tax rate fraction for after-tax cost of debt (default ``0.20``). cost_of_debt: Pre-tax cost of debt fraction. Default: derived from filed interest expense ÷ interest-bearing debt (Nordic uses the net finance-cost line as a proxy), else a 4% estimate; ``quality_notes`` states which. mid_year_convention: Discount cash flows as arriving mid-year (default ``true`` — the standard practitioner convention). Set ``false`` for end-of-year discounting. shares_outstanding: Override the share count. current_share_price: Current price per share. Omit to let the tool fetch the latest completed close internally (Nordic and US alike). net_debt: Override net debt (else derived from the balance sheet). minority_interest: Override non-controlling interests (else the newest balance-sheet figure). The EV→equity bridge deducts this alongside net debt, so per-share value belongs to the parent's shareholders only. include_peer_triangulation: Forward mode — when a stored industry benchmark exists, also price the company with the peer-median EV/EBITDA and EV/EBIT and return a ``triangulation`` block with a combined DCF + multiples fair-value range (default ``true``; silently absent when no benchmark is stored). include_chart: When true, attach a chart JSON for the result. locale: ``"en"`` (default) or ``"fi"`` for chart/labels. Returns: Forward mode: ``{company, market, mode, sector, industry, sector_fit, assumptions, inputs, valuation: {enterprise_value, equity_value, per_share_value, current_share_price, implied_upside, ...}, sensitivity, quality_notes}`` — plus ``triangulation: {industry_group, peer_count, as_of_date, ev_ebitda: {peer_median, company_metric, implied_per_share, ...}, ev_ebit: {...}, fair_value_range_per_share: {low, high, methods}}`` when a stored peer benchmark exists. Reverse mode: ``{company, market, mode, assumptions, inputs, reverse: {implied_fcf_growth, target_equity_value, target_per_share, converged, ...}, quality_notes}``. Implied-expectations mode: ``{company, market, mode, assumptions, inputs, sensitivity_grid: {x_axis, y_axis, x_values, y_values, cells: [[{x, y, per_share_value, enterprise_value, equity_value, implied_upside}, ...], ...], current_share_price, contour_price, base_assumptions}, currency, quality_notes}``. ``cells[y_idx][x_idx]`` maps the (row, col) — pair with ``y_values`` (rows) and ``x_values`` (cols) to render as a heatmap; the contour where ``implied_upside ≈ 0`` marks the assumption set that would justify the current share price. With ``include_chart=true`` the response also carries a self-contained SVG heatmap in ``chart`` and a ready-to-embed ``chart_data_uri`` (``data:image/svg+xml;base64,…``) that any MCP client can drop into a markdown image tag to render the grid inline in chat. Multiples mode: ``{company, market, price: {value, currency, freshness_status, ...}, fundamentals: {market_cap, enterprise_value, shares_outstanding, revenue_ttm, ebitda_ttm, ..., fiscal_year_used}, multiples: {trailing_pe, price_to_book, price_to_sales, ev_to_ebitda, ev_to_ebit, ev_to_sales, fcf_yield_pct}, quality_notes}``. The ``multiples`` block is always present and every key inside it is always present; any multiple whose denominator is missing/zero/negative is ``null`` with an explanation in ``quality_notes`` (an unknown share count nulls all of them at once, because market cap cannot be derived). On miss: ``{"error": "..."}``.

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