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, new_accounting_issue, management_background or fundamentals_analysis on any row to get the individual flags behind it.

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

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

Lists key debates (bull/bear cases) for a company identified by ticker and country. Returns a lightweight summary of each debate — title, description, 1-based order, and generated_at timestamp. 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