Canary Data

Retrieves an existing generated summary using the source document_id from document_search or document_summaries, not a summary ID. Some documents have no summary. Returns an overview, not full text or verbatim quotes; use document_search to find specific statements.

document_summary

Fetch Transactions card-data for a company and dataset. Pick a `dataset` from the menu below (or call `transactions_list_datasets` / `transactions_describe_dataset` to explore). `company` accepts a name, brand, bare ticker, or `SYMBOL:EXCHANGE` identifier (e.g. "Apple", "AAPL", or "AAPL:NASDAQ") and is resolved automatically. When the input matches more than one company the response lists the candidates (status `AMBIGUOUS_TICKER`) so you can re-call with a specific `ticker_exchange`, each marked with `entity_status` the same way as below. Returns `{company, data, narrative_summary, caveats, metadata}`. `data` rows use the post-sanitization columns from `transactions_describe_dataset`. When the data is for an entity that was sold, shut down or added later, `company.entity_status` carries `status`, `label` and `detail`. `REMOVED` means the entity is no longer part of that company as of the date in `label`: its data is history, never present it as part of today's company. `ADDED` means it joined the company on that date, and data before it reflects its prior owner. Without `entity_status` the entity is a current part of its company. ## Response shape Most datasets return `data` as a list of row objects. Wide competitive time-series datasets (e.g. `wallet_share`) instead return `data` in a compact **columnar** form so years of focal-plus-peers history fit one response: "data": {"columns": ["peer_group", "period", ...], "rows": [["CLOSEST_COMPETITORS", "Q2 26", ...], ...]} Map each value in a `rows` entry positionally to the same index in `columns`. No rows or columns are dropped; the keys are simply factored into one header. ## Pagination (columnar datasets) These datasets hold more history than one response can carry, so a call returns the **most recent** whole periods that fit and a cursor for the rest under `metadata.pagination`: "pagination": { "more_history_available": true, "oldest_period_returned": "Q3 23", "next_call": {"tool": "transactions_fetch", "args": {"company": "...", "dataset": "wallet_share", "before": "2023-07-01"}} } To walk further back, repeat the call with the args in `next_call` (the `before` cursor returns strictly older periods). Stop when `more_history_available` is `false`. Periods come back newest-last within each page. Do **not** reach for `date_from`/`date_to`/`days` to get older data on these datasets — they are rejected; `before` is the only way back. ## Pagination (Store Level high-cardinality cuts) `store_level_breakdown` with `store_type: "CITY"` or `"STORE_LEVEL"` supports `top_n`/`offset`/`search`/`rank_by` (defaults: top_n 25, offset 0). This is a **different pagination model** from the columnar cursor above — there is no `before` token to copy. Page forward by incrementing `offset`: "metadata": { "store_type": "STORE_LEVEL", "pagination": {"total": 412, "offset": 0, "top_n": 25, "rank_by": "adjusted_sales", "more_pages_available": true} } Repeat the call with `offset: offset + top_n` from the previous response until `more_pages_available` is `false`. Every other `store_type` value (REGION, STATE, VINTAGE, STORE_AGE_BAND, ALL) returns every row in one call when the payload fits — no `metadata.pagination` block appears then. If the ~25KB budget truncates that response, `metadata.pagination` is added and the same `top_n`/`offset`/`search` params page the dropped stores. ## Datasets [Competitive] wallet_share: Card-transaction-derived WALLET SHARE for a public company against its competitive set: the focal company's and each peer's share of the peer group's combined card spend (by sales, customers, and transactions), the focal's year-over-year share change in points, and share rankings cross_shopping: Card-transaction-derived CROSS-SHOPPING metrics for a public or private focal company against each competitor within one of 5 peer-group cuts — SINGLE_CLOSEST_COMPETITOR, CLOSEST_COMPETITORS (the default), EXPANDED_PEER_GROUP, WALLET_SHARE_LIST, or AI_SUBCATEGORY: customer, spend, and transaction overlap; wallet share inside the served cut; exclusivity; and retained wallet share, each with a year-over-year percentage-point delta and an LTM window variant category_comparison: Card-transaction-derived CATEGORY-LEVEL growth comparison for a public company: the focal company's YoY growth (sales, customers, basket) benchmarked against its category median (including the focal) and its peers' median (excluding it), with the focal-vs-category and focal-vs-peers spreads, an outperformance flag, and the peer ticker list comparison_metrics: Card-transaction-derived COMPETITIVE GROWTH metrics for a public company and its peer set: side-by-side YoY growth (sales, customers, transactions, basket) for the focal and each peer, the focal's growth rankings within the group, its spread versus the peer median, an outperformance flag, and the peer-median benchmark [Customer & Cohort] customer_health: Card-transaction-derived CUSTOMER HEALTH for a public company: the 1-month and 3-month customer churn rates, the new-versus-returning customer mix, and the active-customer index, each with its year-over-year change, by period churn_risk_distribution: Card-transaction-derived CHURN RISK distribution for a public company: the share of the customer base in each of five risk bands (Active through Critical, by recency z-score) per period, with the year-over-year shift, an indexed customer count, the average modeled churn probability, and recency/overdue context engagement_velocity: Card-transaction-derived ENGAGEMENT VELOCITY for a public company: the median days between customer transactions (with the 25th/75th percentiles and the year-over-year change), active-customer counts, average transactions per customer, and a flag for whether engagement is slowing cohort_retention: Card-transaction-derived COHORT RETENTION for a public company: for each acquisition cohort, the period-over-period repeat rate, the cumulative share of the cohort still active, spend retention versus the cohort's first period, and per-customer transactions and spend (including cumulative lifetime spend) cohort_sales_contribution: Card-transaction-derived COHORT SALES CONTRIBUTION for a public company: how each period's projected revenue and spend is distributed across customers acquired in different years, with each cohort's share of the projection, share of total spend and users, and cohort age returns_merchant_credit: Card-transaction-derived RETURNS and merchant-credit activity for a public company: the return (refund/credit) rate as a share of sales dollars and of transactions with its year-over-year change, the average credit amount versus average basket size, and an indexed credit total [Earnings Calendar & Watchlist] upcoming_earnings: Card-transaction-derived UPCOMING EARNINGS outlook for a public company: the next pending quarter's expected earnings date, the predicted beat/miss with the model's calibrated probability, the predicted surprise and YoY projection vs Wall Street consensus (with the spread and prior reported YoY), and a quarter-to-date forward overlay (QTD beat/miss, projection, and whether the pending and QTD signals align) accelerations_decelerations: Card-transaction-derived growth ACCELERATION/DECELERATION for a public company ahead of earnings: the pending quarter's predicted and consensus YoY versus the prior reported YoY, and the implied acceleration (in percentage points) for both the model and consensus — plus the same on a quarter-ahead basis (the following quarter's early projection) watchlist_summary: Card-transaction-derived REVENUE PROJECTION summary for a public company, in the dashboard watchlist shape: the pending quarter's projected YoY with a bull/bear range, Wall Street consensus, predicted surprise, calibrated beat probability, the predicted-side probability shown on the dashboard, and direction, plus the trailing-4-week growth trend all_metric_projections: Card-transaction-derived projections across ALL tracked KPIs for a public company: for each metric type (revenue, gross margin, subscription, net adds, …) the pending quarter's projection vs consensus, predicted surprise, bull/bear range, calibrated beat probability, the predicted-side probability shown on the dashboard, direction, confidence tier, and trailing-4-week trend, plus a QTD forward overlay earnings_preview: Card-transaction-derived EARNINGS PREVIEW for the upcoming, not-yet-reported quarter(s) of a company: the predicted year-over-year revenue growth with its bull/bear range, the consensus estimate, the predicted surprise versus consensus, the beat probability and predicted beat/miss direction, and the confidence tier earnings_review: Card-transaction-derived EARNINGS REVIEW of already-reported quarters: how the card-based prediction compared with the reported result — predicted vs consensus vs reported year-over-year revenue growth, the predicted and reported surprise, the predicted and reported beat/miss direction, and whether the prediction called the direction right [Gross Margin] quarterly_gross_margin_predictions: Card-transaction-derived quarterly GROSS MARGIN surprise outlook for a public company: the predicted year-over-year gross-margin change (in percentage points) with a bull/bear range, Wall Street consensus, the predicted surprise vs consensus, predicted direction (beat/miss) with the model's probability, a confidence tier, and — for reported quarters — the actual change and whether the call was right quarterly_gross_margin_detail: Card-transaction-derived quarterly GROSS MARGIN levels for a public company: the predicted gross-margin percentage with a bull/bear range, Wall Street consensus, and the reported margin, alongside the year-over-year margin change (in percentage points) and the average basket size [Mix & Detail] channel_mix: Card-transaction-derived ONLINE vs OFFLINE channel mix for a public company: each channel's share of the company's sales, customers, and transactions, the year-over-year share shift in points, and per-channel YoY growth and intensity (basket size, trips per customer) price_points: Card-transaction-derived PRICE-BAND mix for a public company: how sales, customers, and transactions are distributed across price quintiles (low to high ticket), the year-over-year share shift in points, per-band YoY growth, basket size, and the band's dollar bounds demographics: Card-transaction-derived DEMOGRAPHIC breakdown of a public company's sales: per segment (region, CBSA tier, leading market, urbanicity, age cohort, generation, gender, state, CBSA metro) the YoY growth in sales/customers/transactions, the over/under index versus the US population, the year-over-year sales-share shift, and the population-weighted average sales share brand_entity_mix: Card-transaction-derived BRAND/SEGMENT mix for a multi-brand company: each card-tracked brand's share of the company's total sales, customers, and transactions, its year-over-year share shift in points, per-brand YoY growth, and approximate dollar sales (millions) store_level_breakdown: Card-transaction-derived STORE LEVEL breakdown for a public company: per store (cut by `store_type` — REGION, STATE, CITY, STORE_LEVEL, VINTAGE, STORE_AGE_BAND, or ALL) the year-over-year growth in sales/customers/transactions, its share of company sales with the year-over-year share shift in points, an indexed sales level, and (REGION/STATE) sales over/under vs population in percentage points [Revenue & Surprise] quarterly_revenue_predictions: Card-transaction-derived quarterly REVENUE (top-line) surprise outlook for a public company: the card-implied YoY revenue projection with a bull/bear range, Wall Street consensus YoY, the predicted surprise vs consensus, predicted direction (beat/miss) with the model's probability, a confidence tier, and — for reported quarters — the actual YoY and whether the call was right quarterly_revenue_predictions_card_optimal: Card-transaction-derived quarterly REVENUE surprise outlook for a public company built on the card-optimal KPI — the single card-tracked metric (e revenue_prediction_track_record: Backtest accuracy track record for a public company's card-derived quarterly revenue-surprise predictions: how well past predictions matched reported results [Sales & Momentum] sales_decomposition: Card-transaction-derived SALES growth decomposition for a public company: the surprise-implied year-over-year sales growth split into its additive drivers — customer growth, transactions-per-customer growth, and basket-size ($/transaction) growth (sales YoY = customers + txn/customer + $/txn) — plus absolute index levels for each sales_decomposition_card_optimal: Brand/segment-level SALES growth decomposition for a multi-brand public company: the same surprise-implied YoY decomposition (customers, transactions-per-customer, basket size) and index levels as sales_decomposition, scoped to a single card-tracked brand inside the ticker latest_card_activity: Daily card-spending momentum for a public company over the most recent data window: day-by-day projected sales year-over-year growth, a trailing-7-day growth trend, Wall Street consensus YoY, and absolute sales index levels (current vs prior year), with holiday flags latest_card_activity_card_optimal: Brand/segment-level daily card-spending momentum for a multi-brand public company: the same recent daily sales YoY, trailing-7-day trend, consensus, and index levels as latest_card_activity, scoped to a single card-tracked brand

transactions_fetch

Screens the whole company universe for flags and returns one row per matching company. Use this when the question is "which companies have X?" rather than "what does company Y have?". Every other flag tool needs a ticker up front; this one finds the tickers. Each row identifies a company and summarises what it matched: flag count, the flag types hit, the most recent flag date, and a severity breakdown. To go deeper on any company in the result, pass its `ticker` and `country` straight into `insider_trading`, `fraud_and_malfeasance`, `accounting_and_disclosure`, `management_background` or `fundamentals_analysis` — no lookup step in between. ## Saying what to screen for Two ways, and exactly one is required: * `category` — screen a whole group at once. Prefer this for broad questions ("any management issue", "anything accounting-related"). Its flag types are resolved live, so it keeps up with taxonomy changes. * `flag_types` — name exact types when the question is specific. An unrecognised name is rejected and echoed back, never answered with an empty result. ## What the dates mean Windows filter on the date the event **happened**, not the date Canary detected it. "In the last month" means the executive departure, restatement or filing occurred in the last month. ## Scope Active companies only. **No market-cap floor** — small caps are included, so a result is not limited to well-known names. A bounded window is always required, which is why there is no "all history" option: an unbounded screen of the entire flag history has no natural size. ## Matching the web Screen page This returns the same companies as the Canary web Screen page given equivalent filters. A disagreement is a bug worth reporting, not expected variance.

flag_screen

Returns Canary's Forensic Accounting Report for a company — an AI-generated analysis that adjusts reported figures for known accounting anomalies and benchmarks them against analyst consensus. **How to use the response:** - `available` — check this first. If false, no report exists yet for this company. Tell the user: "Canary hasn't generated a forensic accounting report for this company yet. Coverage expands regularly — check back later." Do not attempt to read other fields. - `key_takeaways` — start here. A plain-language narrative summary of the most significant accounting findings. Read this before any structured data — it is the primary output. - `waterfall` — the structured accounting breakdown. Contains: - `periods`: list of fiscal period labels (e.g. ["FY2022", "FY2023", "FY2024"]) - `labels`: row names (e.g. "Reported Revenue", "Accrual Adjustment") - `types`: row type for each label ("reported", "adjustment", "adjusted", "consensus") - `values`: 2D array — values[row_index][period_index], null where data is unavailable - `notes`: per-row annotation strings (null when no note) - `summary_comparison` — reported vs. adjusted vs. consensus across key metrics in tabular form. Use for a concise multi-metric overview. - `flag_types_used` — list of accounting signal identifiers that triggered this analysis (e.g. ["accounts_receivable_growth", "recurring_one_time"]). Use these to explain what specific anomalies Canary detected. - `appendix` — supplementary analysis sections with deeper per-adjustment explanations. May be absent for some reports. - `metadata` — report provenance: `generated_at` (ISO 8601 timestamp), `model` (Gemini version used), `version` (integer report version), `periods` (period labels if present). Surface `generated_at` only if the user asks how fresh the data is. Use this tool to answer questions like: - "What is Apple's quality-adjusted revenue vs. consensus?" - "Has this company been systematically overstating earnings?" - "Which accounting adjustments are the largest and why?" Requires `ticker` (e.g. "AAPL") and `country` ISO code (e.g. "US"). Both fields are always required — country is needed for exact entity matching even for globally unique tickers. If the user does not provide a country, ask for it before calling the tool.

accounting_waterfall

Retrieves fraud & malfeasance flags for a company by ticker and country. Combines two flag categories — `illegal_or_questionable` (fraud, illegal activity, stock manipulation, investigations, regulatory scrutiny, civil lawsuits) and `questionable_associations` (problematic shareholders, underwriters, business partners, SPAC/reverse-merger history, stock promoters, and listing-jurisdiction risk). Both categories' flag types are resolved live from `flag_type_categories`, so the tool tracks taxonomy changes without code edits. Returns flags only; the internal `fraud` score is not exposed via MCP.

fraud_and_malfeasance

Retrieves fundamental business risk flags for a company by ticker and country. Returns every flag in the `fundamental_business` category — declining sales and margins, going-concern letters, financial distress, competitive and AI/positioning shifts, and the broader fundamentals-metrics signals — not a single flag type. The category's flag types are resolved live from `flag_type_categories`, so the tool tracks taxonomy changes without code edits.

fundamentals_analysis

Returns Canary's Fundamentals Metrics for a company — an AI-generated scorecard of 60 metrics across four sections (Market, Business, Sales, Margins), each with a 1-5 score, a one-year trend, and a one-sentence rationale. **Scoring direction — read this first:** every score is normalized so that 5 always means "favorable for the business" and 1 always means "unfavorable," regardless of which raw direction that implies for the specific metric. Low customer concentration, low capital intensity, low country risk, and low cyclicality all score toward 5, not 1. Underearning (understating true earnings power) scores better than overearning. Do not assume "high underlying number = high score" — always read the `rationale` if the direction isn't obvious from the metric name alone. Trend follows the same convention: "improving" always means moving toward more favorable for the business (e.g. "improving" on Churn means churn is going down). Scores are calibrated across companies so that a 3 is a genuine median outcome, not a warning sign — only roughly the top and bottom 15% of companies land on 5 or 1 for any given metric. **How to use the response:** - `available` — check this first. If false, no scorecard exists yet for this company. Tell the user: "Canary hasn't generated fundamentals metrics for this company yet. Coverage expands regularly — check back later." Do not attempt to read other fields. - `metrics` — a flat list of all 60 metrics. Each entry is an object with: - `section`: one of "Market", "Business", "Sales", or "Margins" - `metric`: the metric name (e.g. "Pricing power", "AI winner or loser") - `score`: integer 1-5, or `null` - `trend`: one of "improving_a_lot", "improving", "neutral", "worsening", "worsening_a_lot", or `null` - `rationale`: one sentence explaining the score, sourced from web search (not Canary's proprietary data) `score` and `trend` are always either both present or both `null` together. When both are `null`, the metric was deliberately judged not applicable to this company — `rationale` will read "Not applicable." Skip these when summarizing strengths/weaknesses; they are not missing data and not a weakness, they're a documented non-answer. To describe a company's profile in a section, filter `metrics` by `section` and look at the spread of scores — e.g. mostly 4s and 5s in "Margins" indicates a structurally strong margin profile. To find the single strongest or weakest attribute overall, sort by `score` across all sections. - `metadata` — `updated_at` (ISO 8601 timestamp of the last regeneration — there is no history, only the latest snapshot), `total_metrics` (always 60), `section_counts` (metric count per section, keyed by section name), `scored_metrics_count` (how many of the 60 have a non-null score for this company — the rest were judged not applicable). Surface `updated_at` only if the user asks how recent the data is. Use this tool to answer questions like: - "Is this company an AI winner or loser, and why?" - "How strong are this company's margins relative to what you'd expect?" - "What's driving the growth outlook for this company?" - "Does this company have pricing power?" This is the metric-level view of business quality. It is a different dataset than `business_quality_score` (one holistic A-F letter grade, not a roll-up of these metrics) and more granular than `fundamentals_analysis` (a short list of flags derived from a subset of these same 60 metrics when they cross a threshold). Use this tool when the user wants the full underlying picture across all four sections, not just a single grade or a triggered-flag summary. Requires `ticker` (e.g. "AAPL") and `country` ISO code (e.g. "US"). Both fields are always required — country is needed for exact entity matching even for globally unique tickers. If the user does not provide a country, ask for it before calling the tool.

fundamentals_metrics

Retrieves insider trading flags (all sub-types) for a company by ticker and country.

insider_trading

Retrieves the full historical time series for a specific KPI metric. Use the `id` of any KPI entry returned by the `kpi_snapshot` tool to fetch all historical values for that metric and company, ordered from most recent to oldest. Values are extracted from earnings call transcripts and podcast episodes. Every entry names its origin in `document_type`, and `document_type` can be passed to restrict the series to one of them (`call_transcript` or `podcast`). Supports date range filtering and cursor-based pagination.

kpi_history

Returns the full bull/bear debate for a single key debate, selected by order. Use `key_debates_list` first to retrieve available debates and their order values. The `order` field is 1-based and may shift between regenerations — if the requested order is no longer present, re-list to get current debates.

key_debates_detail

Lists key debates (bull/bear cases) for a company by ticker and country. Returns a lightweight summary of each debate — title, description, order, and generated_at. Use `key_debates_detail` to retrieve the full bull/bear cases and evidence for a specific debate by its order.

key_debates_list

Lists valid document_search types, category groupings, and default types. Pass exact leaf values as document_types, not category labels. Omit document_types or pass [] to search with defaults without calling this tool.

list_document_types

List the Transactions card-data datasets available through `transactions_fetch`. Returns one entry per dataset: `key`, `title`, `category`, `shape`, and a one-line summary. Optionally filter by `category` (substring, e.g. "Revenue") or `query` (keyword matched against key/title/summary). When to use: to discover which dataset answers a question before calling `transactions_fetch`. When NOT to use: to fetch the actual data (use `transactions_fetch`) or to resolve a company ticker (use `transactions_resolve_company`).

transactions_list_datasets

Retrieves management track-record & background flags for a company by ticker and country. Returns every flag in the `management_track_record` category — executive and board turnover, prior bankruptcies/delistings, related-party transactions and insider-enrichment, nepotism, poor capital allocation, insider buying/selling behaviour, and related governance signals. The category's flag types are resolved live from `flag_type_categories`, so the tool tracks taxonomy changes without code edits. Returns flags only; the internal `insider` score is not exposed via MCP.

management_background

Resolve a company name, brand, or ticker to a canonical `SYMBOL:EXCHANGE` identifier for Transactions card data. Accepts bare tickers (e.g. "NKE"), exchange-qualified tickers (e.g. "NKE:NYSE"), company names, or Canary brand names. Returns a single resolved company when unambiguous, a candidate list when multiple matches exist, or a not-found status when nothing matches. Use before `transactions_fetch` when the caller only has a fuzzy name or bare symbol rather than a `SYMBOL:EXCHANGE` identifier. A result for an entity that was sold, shut down or added later carries `entity_status` with `status`, `label` and `detail`. `REMOVED` means the entity is no longer part of that company as of the date in `label`: never present it as part of today's company. `ADDED` means it joined the company on that date, and history before it reflects its prior owner. A result without `entity_status` is a current part of its company.

transactions_resolve_company

Search for 13F-linked companies by name, ticker, or partial phrase. Use this tool to resolve a company name or ticker to its `entity_id`. Many names collide, so the search step prevents agents from having to guess the exact id. Returns up to 25 ranked matches. An empty result list is a valid response — it means no company matched the query.

thirteenf_search_companies

Search for 13F investment firms by name or partial name. Use this tool to resolve a fund name to its CIK before calling `thirteenf_firm_detail` or `thirteenf_firm_holdings`. Many funds share similar names (e.g. multiple "Vanguard" or "BlackRock" entities), so the search step prevents agents from having to guess the exact CIK. Returns up to 25 ranked matches ordered by trigram similarity + prefix bonuses. An empty result list is a valid response — it means no firm matched the query.

thirteenf_search_firms

Searches document text. Start here for "What did the company say about X?" Returns snippets, IDs, and links, newest-first. Omit keywords to browse. Each canary_url opens this search in the Canary web app with that document selected: share it so the user can read the full document and explore the results in detail. Documents may contain third-party commentary: attribute statements to the speaker. Search related terms with OR; retry irrelevant results with exact: true. Check meta.has_more and filters. Snippets are partial: report findings, never infer absence.

document_search

Returns the SuperAnalyst monitoring plan for a company by ticker and country. The plan contains KPIs grouped into sales, costs, and (optionally) other_key_metrics categories. Each KPI has a list of monitoring methods with a name and rationale.

superanalyst_monitoring_plan

Lists active SuperAnalyst questions for a company by ticker and country. Returns questions grouped by category. Each group has a human-readable `category` label and a `questions` list. Each question entry has a 1-based global `order` (display label only), a stable `id` (UUID selector), the `question` text, and `why_important`. Use `superanalyst_research_plan` with the `id` from an entry to fetch its research plan — `order` is a display label only and must not be used as a selector. Only categories that have at least one active question are included.

superanalyst_questions_list

Returns the research plan for a single SuperAnalyst question, selected by its stable id. Use `superanalyst_questions_list` first to retrieve available questions and their `id` values. Pass the `id` from the question the user referred to — `order` is a display label only. If the requested id is no longer present (question archived or replaced), re-list to get current questions.

superanalyst_research_plan

Lists all mentions of a single topic across a company's earnings call transcripts and podcast episodes. Use the `topic_id` of any entry returned by the `document_topics` tool to page through every mention (the spoken sentences) of that topic for the company, ordered from most recent to oldest. Each mention names the `document_type` it came from. Pass `document_type` to restrict mentions to one source type — `call_transcript` or `podcast`. Omit it to receive both. Supports date range filtering and cursor-based pagination.

document_topic_mentions