MCP Server — Developer Documentation

Screens the whole company universe for flags and returns one row per matching company — the answer to “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.

Three things about scope that are not visible in the schema. Dates are event dates — “in the last month” means the departure, restatement or filing happened in the last month, not that Canary detected it then. Active companies only. And there is no market-cap floor, so small caps are included; a result is not limited to well-known names. This screen intentionally returns the same companies as the Canary web Screen page given equivalent filters — a disagreement is a bug worth reporting, not expected variance.

Naming what to screen for

Supply exactly one of category or flag_types. category is the normal path: five values, covering a whole group at once, with the flag types behind it resolved live so it keeps up with taxonomy changes. flag_types is the precise path, for when the question is about specific types. It is validated against the live taxonomy — an unrecognised name is rejected with the offending value named, never silently answered with an empty list.

Choosing a window

Supply exactly one of time_range or since. time_range takes a named bucket; since takes an ISO 8601 date, for windows the buckets cannot express. There is deliberately no “all history” option: a bounded window is what keeps a universe-wide screen to a usable size.

Input Parameters

Response Shape — companies found

Response Shape — no companies found

When data is empty, meta.coverage is included as a hint, echoing whichever of category or flag_types was screened. It says explicitly that the filters were understood, so an empty result reads as “nothing matched this window” rather than “the request was not recognised”.

Drilling into a result

A flag_screen row hands back ticker and an ISO-2 country — exactly the input the per-company flag tools take, with no lookup step in between. Screen to find the companies, then call insider_trading, fraud_and_malfeasance, accounting_and_disclosure, management_background or fundamentals_analysis on any row to get the individual flags behind it.

Flag Series — one tool, two views of the same captured contract. Use view to choose the surface. Omit it (or pass observations) for the dated numbers at the grain they were published; catalog to see what the company publishes before fetching any of it. It complements the flag tools rather than replacing them: they still return every flag with its published text, and this tool adds the figures Canary has captured from those flags as labelled series.

The two views

observations (default) — each row is one number for one metric over one period: metric, value, unit, period_start, period_end, grain, transform, basis, and whether the reading was provisional. available_metrics is returned on every call. catalog — one small call answers “what does this company have” without paging through its flags. For every series: the metric name (verbatim), whether it is the company’s own reported_figure or a third-party proxy, the arithmetic already applied, the grain, and the first/last period observed. A company with nothing plottable returns an empty data array, not an error. Reported-only questions — two years of revenue growth vs last-quarter revenue — use catalog then observations with metric: "revenue" (yoy for growth, latest level for the last quarter). Do not treat the company as a tracker: tracker is a flag family, not an ingest path.

When nothing is captured

Trackers are often published before their figures are captured, so an empty result is not the absence of data. Every view then returns the most recent published readings in readings (date, title, text, company), and readings_in_full names the flag tool that returns those same flags complete, with sources and summaries; meta.published_readings says how many there are. On the observations view, page and per_page page those readings whenever no series is captured, and readings_page carries total and has_more. The catalogue lists the trackers a company publishes only as text in text_only_trackers; ask for one by name as series and its readings come back.

What family covers

tracker — Canary’s own recurring readings, monthly and sub-monthly. Tracker is a flag family, not an ingest path and not a property of the issuer: Microsoft is not “a tracker” unless one of those readings is filed under it. margin — the margin_compression and margin_expansion flags, carrying quarterly revenue, ebit_excl_sbc and ebit_margin. buyback — the share_repurchases flags, carrying quarterly amounts and shares repurchased, as filed. One request shape for all three. Note that margin carries reported revenue from filed financials while a tracker series is a proxy — export value, a price index. Where a company has both, present the reported series as actuals and the tracker as a leading indicator; the family field on every observation is what keeps them apart. family filters observations only; catalog returns every family.

Metric names are verbatim, and that matters

metric is copied from the source that published it, so the same tracker reports different metrics for different companies. The Memory Tracker publishes a DRAM price index for Micron and a Korean-customs export value for SK hynix and Samsung. Neither is revenue and neither is sales — export value is a proxy for sales, and a price index is not a volume series at all. There is no synonym table behind this tool: asking for metric: "sales" on a company whose only series is a price returns no data plus available_metrics, and that is the correct answer. Label a chart with the metric string returned here, never with a name inferred from the tracker’s title.

Reading an observation

transform says what arithmetic the number already is — level, yoy, qoq, mom, t3m_yoy, t12m_yoy. These are already computed; do not recompute them, and note that each metric exposes exactly one y/y convention. unit and scale are not decoration: an ebit_margin of 0.7632825 is a ratio (a 76.3% margin), a margin_exp_comp_by_year of 3488.856 is a change in basis points and not a growth rate, and currency figures come back at scale: "units" — base currency units, not the millions a CapIQ screen shows. SK hynix FY2026 Q2 revenue is 79318746000000 KRW here and 79318746 in CapIQ; they are the same quarter, so do not rescale. A currency figure is never returned without its ISO currency. basis distinguishes working_day_adjusted from raw_unadjusted, and a reading normally publishes both for the same metric — never mix them in one line. attribution: "undifferentiated" marks an observation the source itself says is not company-specific. caveats carries the reading’s own qualifications, and meta.uncaptured_readings counts readings whose figures could not be read, so a short series is distinguishable from a complete one.

Input Parameters

Catalog response shape (view: "catalog")

Retrieves accounting & disclosure flags for a company identified by ticker and country — the full set shown on the web Accounting tab, spanning the entire accounting_and_disclosure category (revenue/cost recognition, receivables, inventory, auditor and disclosure changes, new accounting issues, and more). Returns paginated flag records, each containing the flag date, severity, title, description, sources, and a metadata map (filing URLs and forms for filing-comparison flags).

Input Parameters

Response Shape — flags found

Response Shape — no flags found

When data is empty, meta.coverage is included as a hint. It carries the echoed ticker and country so the caller can confirm the parameters that were searched, along with a human-readable hint string. When a date_from or date_to filter was supplied, the active date bounds are also echoed and the hint clarifies that the empty result is specific to the requested range — flags may exist outside it.

Response Shape — no flags found (with date range)

Retrieves insider trading flags (all sub-types) for a company identified by ticker and country. Returns paginated flag records derived from regulatory filings, each containing the flag date, severity, description, and structured transaction details.

Input Parameters

Response Shape — flags found

Response Shape — no flags found

When data is empty, meta.coverage is included as a hint. It carries the echoed ticker and country so the caller can confirm the parameters that were searched, along with a human-readable hint string. When a date_from or date_to filter was supplied, the active date bounds are also echoed and the hint clarifies that the empty result is specific to the requested range — flags may exist outside it.

Response Shape — no flags found (with date range)

Retrieves fundamental business risk flags for a company identified by ticker and country — the full set shown on the web Fundamentals tab, spanning the entire fundamental_business category (declining sales and margins, going-concern letters, financial distress and high leverage, customer/supplier concentration, competitive and country risk, and AI/competitive positioning shifts). Returns paginated flag records, each containing the flag date, severity, title, description, sources, and a metadata map whose shape varies by flag type.

Input Parameters

Response Shape — flags found

Response Shape — no flags found

When data is empty, meta.coverage is included as a hint. It carries the echoed ticker and country so the caller can confirm the parameters that were searched, along with a human-readable hint string. When a date_from or date_to filter was supplied, the active date bounds are also echoed and the hint clarifies that the empty result is specific to the requested range — flags may exist outside it.

Response Shape — no flags found (with date range)

Retrieves fraud & malfeasance flags for a company identified by ticker and country — combining two 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). Returns paginated flag records, each containing the flag date, severity, title, description, sources, and a metadata map whose shape varies by flag type.

Input Parameters

Response Shape — flags found

Response Shape — no flags found

When data is empty, meta.coverage is included as a hint. It carries the echoed ticker and country so the caller can confirm the parameters that were searched, along with a human-readable hint string. When a date_from or date_to filter was supplied, the active date bounds are also echoed and the hint clarifies that the empty result is specific to the requested range — flags may exist outside it.

Response Shape — no flags found (with date range)

Retrieves management track-record & background flags for a company identified by ticker and country — the full 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. Returns paginated flag records, each containing the flag date, severity, title, description, sources, and a metadata map whose shape varies by flag type.

Input Parameters

Response Shape — flags found

Response Shape — no flags found

When data is empty, meta.coverage is included as a hint. It carries the echoed ticker and country so the caller can confirm the parameters that were searched, along with a human-readable hint string. When a date_from or date_to filter was supplied, the active date bounds are also echoed and the hint clarifies that the empty result is specific to the requested range — flags may exist outside it.

Response Shape — no flags found (with date range)

Retrieves the most recent KPI per metric for a company identified by ticker and country. Returns one entry per distinct metric (e.g. Revenue, EPS, Active Users), each showing the value from the most recent source document. KPIs are extracted from earnings call transcripts and podcast episodes, and every entry names its origin in document_type. Because only the newest value per metric is returned, a recent podcast figure can take the place of an earnings-call one — pass document_type=call_transcript for the earnings-call-only view. Supports filtering by metric type and date range. Use the after / before cursors for pagination. Use id values from the response entries to fetch full historical time series with the kpi_history tool.

Input Parameters

Response Shape

Retrieves the full historical time series for a specific KPI metric identified by the id of any entry returned by kpi_snapshot. Returns all historical values for that metric and company, ordered from most recent to oldest. Values are extracted from earnings call transcripts and podcast episodes, and every entry names its origin in document_type — pass document_type to restrict the series to a single source. Supports date range filtering and cursor-based pagination.

Input Parameters

Response Shape

Searches Canary documents by company, type, date, and optional keywords, returning the newest matches with document metadata, matching sentence snippets, page metadata, and a canary_url. The URL opens the same search in the Canary web app with that document selected, so the user can View in Canary to read the full document and keep exploring the results on the web. It carries the search filters as query parameters (resolved entityIds, compactly encoded keywords, types and typeGroups) that the web app restores on open.

Each keyword has text and optional exact. Exact keywords skip synonym expansion but retain stemming and adjacent-phrase matching. Exact and non-exact keywords may be mixed and combined with AND or OR. Omit document_types or pass an empty array ([]) to use Canary's current defaults; call list_document_types only when a specific type is needed. Request the next page until data is empty. Invalid filters are rejected without exposing upstream errors.

Input Parameters

Example

Response Shape

Lists all searchable leaf document types, their categories, and default_types. This tool takes no input. Use it before document_search only when the search needs a specific document type.

Response Shape

Retrieves the stored summary for one document. Pass the document_id from document_search or document_summaries, not the summary ID. Returns an error if no summary is available; it does not generate a summary or retrieve the full document.

Input Parameters

Response

A single object containing id (summary ID), document_id, filing_date, document_type, and summary. Summary content is returned as structured JSON when stored in that format, otherwise as plain text.

Retrieves the most recent document summaries for a company identified by ticker and country. Summaries are generated from the company's earnings call transcripts and podcast episodes, and returned newest-first. Each entry contains the summary content along with the source document_id, its filing_date, and the document_type it came from — pass document_type to restrict results to a single source. Supports date range filtering and cursor-based pagination via the after / before cursors.

Input Parameters

Response Shape

summary is a structured object with the sections business_performance, outlook, changes_from_previous_call, challenges, and opportunities. Legacy plain-text summaries are returned as a string.

Lists the most recent topics discussed in a company's earnings call transcripts and podcast episodes, identified by ticker and country. Returns one entry per company-specific topic, newest-first, each with its category, document_count (how many of the company's documents mentioned it), and up to 5 example mentions (the spoken sentences). A topic can span both source types, so the topic itself carries no document_type — each individual mention names the document it came from. Pass document_type to restrict both the topics and their mentions to one source, in which case document_count counts only documents of that type. Use a topic id with the document_topic_mentions tool to page through all of its mentions. Supports date range filtering and cursor-based pagination.

Input Parameters

Response Shape

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 document_topics 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 a single source. Supports date range filtering and cursor-based pagination.

Input Parameters

Response Shape

Lists active SuperAnalyst questions for a company identified by ticker and country. Returns questions grouped by category (Market, Business Performance, Unit Economics, Competition, Accounting, Insider Behavior, Challenges, Opportunities). Each entry includes a 1-based display order, a stable id (UUID), the question text, and a why_important explanation. Pass the id to superanalyst_research_plan to retrieve the full research plan — order is a display label only and must not be used as a selector.

Input Parameters

Response Shape

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.

Input Parameters

Response Shape

Returns the SuperAnalyst monitoring plan for a company identified by ticker and country. The plan groups KPIs into sales, costs, and optionally other_key_metrics. Each KPI includes a list of monitoring methods with a name and rationale (why). Use this to understand how to track key business drivers ahead of earnings.

Input Parameters

Response Shape

Returns the business description for a company identified by ticker and country: five sections covering business_model, market, competition, challenges and opportunities. Each section has its text, or is null until it has been generated. Charts are not included. Coverage is limited to the SuperAnalyst universe; a company outside it, or one with no overview yet, returns an error rather than an empty result.

Input Parameters

Response Shape

Lists key debates (bull/bear cases) for a company identified by ticker and country. Returns a lightweight summary of each debate — title, description, and 1-based order. Use key_debates_detail with a debate's order to retrieve the full bull/bear cases and supporting evidence.

Input Parameters

Response Shape

Returns the full bull/bear debate for a single key debate selected by its 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.

Input Parameters

Response Shape