Hub-Equity MCP

Build a comparison matrix for N entities × M concepts at one period. Cap N=10, M=10 (more answers a 422 validation error). ALWAYS prefer this over N×get_fact when comparing more than one company. Returns one row per entity with metadata (sector, country, auditor) + a `cells` map keyed by hub_concept_code → CompareCell. Consolidated values only, one value per (entity, hub, year), aligned on the calendar: for each issuer, the fiscal year whose `period_end` falls in `fiscal_year` (FY forced). A non-December filer can therefore read a different value here than from get_fact for the same fiscal_year.

Compare two annual filings of the SAME entity side-by-side. Use when the user asks "what changed at X between FY{n-1} and FY{n}", "X year-over-year breakdown", "compare X's balance sheet year by year". Pivots the normalized values of the same entity on two fiscal years and surfaces semantic flags: `is_new_in_b` (concept appeared), `is_removed_in_b` (concept disappeared), `is_sign_flip` (positive↔negative), and `has_restatement_warning` (filing_b's comparative columns retroactively restated filing_a's value). `hub_concept_codes` is optional. None = a default set of primary hubs across income statement / balance sheet / cash flow. Pass an explicit list (up to 50) to override. `form_type` picks the reference filing of each year: `10-K`, `20-F`, `40-F`, `annual_report` (ESEF filers), or an amended form (`10-K/A`, `20-F/A`, `40-F/A`). Omit it (default) for the most recent original annual filing of each year, whatever its form. Different from `compare_entities` (cross-entity), `get_amendment_diff` (10-K vs 10-K/A same year), and `get_metric_history` (one metric, time series).

Convert an amount between two ISO 4217 currencies using ECB reference rates. `rate_type` ∈ {closing, average_ytd, average_prior_year}: - closing (default) → spot rate at `date` (balance-sheet items per IAS 21) - average_ytd → avg over the 365 days ending at `date`, a rolling window, not year-to-date (P&L / cash flow items) - average_prior_year → avg over the calendar year before `date` `date` is YYYY-MM-DD (defaults to today). Identity short-circuit when from == to. An unsupported currency code returns an error result. Cross-rates (e.g. USD→JPY) are computed through EUR. `fix_date` echoes the requested date: the rate used is the latest ECB fixing available on or before it. Use when the user asks "convert X in Y", "Microsoft revenue in EUR", "what's the average USD/EUR rate for FY2024 P&L conversion?".

Search Hub-Equity entities by name, ticker (e.g. 'CSCO'), or CIK. Returns up to 5 matches ranked by exactness. Use this first when the user mentions a company by name or ticker - you need the entity_id to call any other tool.

Per-concept restatement diff (old_value, new_value, diff_pct, kind) across all 10-K/A amendments of an entity. Sorted by |diff_pct| desc. Differs from `get_amendments` (which returns counts per amendment): this tool flattens the per-concept changes and filters by materiality (`min_diff_pct`, default 1%) and optionally by hub_concept_code or kind. Use for 'what specifically changed in the FY24 10-K/A?', 'show all REVENUE restatements', 'material accounting corrections only'.

Surface 10-K/A restatements for an entity (per-concept diffs when available). Use when the user asks 'has X amended any filing?', 'restatements?', 'what changed in the FY20xx 10-K/A?'.

The issuer's own arithmetic in one filing: which concepts add up to which total, with the sign the filer declared (`weight`) next to the sign the filed values support (`corrected_weight`); `is_corrected` marks an arc where the two disagree, `corrected_count` counts them. Call it first without `link_role` to list the filing's calculation sections (largest first), then again with the `link_role` of the statement or note you want. Take `filing_id` from the `source` of `get_fact` or from `get_entity_profile`. Use for 'how does Apple's FY2025 balance sheet add up', 'which lines make up operating expenses in this filing', 'did the issuer get a sign wrong'.

How complete Hub-Equity's data is for an entity: a grade from A+ to D, or none. The grade is computed on the latest reported fiscal year and is the worse of two gates: the core concepts every listed issuer publishes, and the concepts this company itself reports. A missing grade is not a bad grade. The result also carries the counts behind each gate, the direct vs derived split, GAAP/IFRS presence and the freshness of the latest filing. Use when the user asks how reliable a company's data is.

Comprehensive company snapshot: identifiers, sector, auditor, employees, legal form, fiscal year end, recent filings summary. Use after `find_entity` when the user wants context, or as a first call when the user asks 'tell me about <company>' / 'qui est <entreprise>'.

Issuer-specific qnames declared outside standard taxonomies (us-gaap / ifrs-full). Returns up to `limit` (cap 100) extension concepts sorted by usage_count desc. `status_filter` ∈ {all, mapped}: `mapped` keeps the extensions Hub-Equity reads into a standardised hub. For each extension: qname, label, item type, period type, balance, usage count, the issuer's own documentation and the standard concept it is anchored to (ESEF). Use for 'what custom concepts has Apple declared?'.

Get a normalized financial value for an entity at a given period. `hub_concept_code` is a Hub-Equity standardized code (e.g. 'REVENUE', 'NET_INCOME', 'TOTAL_ASSETS', 'OTHER_CURRENT_LIABILITIES'). Use `search_concept` first if you don't know the code. `fiscal_period_type` defaults to FY; the served values are annual, and another period type is refused with an error. When nothing is served for that combination, the call returns an error result that says so: never fill the gap with an estimate.

Decompose a financial fact into its constituent parts. Pass EITHER `hub_concept_code` (preferred - e.g. TOTAL_ASSETS) OR `qname` (raw XBRL like 'us-gaap:DeferredRevenueNoncurrent') for concepts without a hub mapping. Returns three layers: 1. `rollup_children` - the components this issuer reported for the figure, with their sign, on a paid plan; empty below it, with a note. 2. `linkbase_children` - XBRL calc linkbase children, RECURSIVE up to `depth` (max 3). Each child has its own `children` list. 3. `dimensional_breakdown` - axis/member slices (segment, geography), on a paid plan; empty below it, with a note. `depth=1` is open to every caller. On a paid plan, use `depth=2` for aggregates (TOTAL_ASSETS, TOTAL_LIABILITIES) to get the full breakdown tree in ONE call instead of N round-trips.

N-year time series for one metric (annual values only), with YoY growth (null across a missing year) and CAGR computed. Use for trend / growth questions: 'evolution of revenue over 5 years', 'CAGR du CF operating', 'Microsoft net income trend'.

Dimensional breakdown of a metric (axis/member from XBRL dimensions). Use for 'revenue par région', 'profit by segment', 'split by product/geography'. Reads the dimensional (segment) values for the given period. Returns empty `axes` when the issuer reported only the consolidated total. The members of each axis need a paid plan: below it the axes are listed without them, with a note.

Per-concept silent restatements (old_value, new_value, diff_abs, diff_pct, kind, label, both filings as sources), sorted by |diff_pct| desc. `get_amendment_diff` on the other source: figures a later filing reprinted differently in its comparative columns, with no amendment filed. Filters by materiality (`min_diff_pct`, a fraction, default 1%), hub_concept_code and kind (`modified`, or `added` for a newly disclosed figure). Use for 'all silent REVENUE restatements of X', 'material quiet revisions only', 'which filing revised FY2023 and by how much?'.

Figures a later filing reprinted differently in its comparative columns, with no amendment filed, grouped by the filing that revealed them. The restatements `get_amendments` cannot see: most restatements are never filed as a 10-K/A or an amended ESEF report. `fiscal_year` is the year of the restated figure. `diff_pct` is in percent. Use for 'did X quietly change its past numbers?', 'restatements without an amendment', 'was FY2023 CapEx revised later?'.

Surface the checks Hub-Equity ran on the numbers of a filing. Check types: `accounting_equation` (Assets = Liabilities + Equity), `calculation_filing` and `calculation` (a parent of the issuer's calculation linkbase against the weighted sum of its children), `hub_calculation` (consistency of the standardized roll-ups) and `dqc_*` (XBRL US data-quality rules, reported as `info`). `validation_type` is one of: `accounting_equation` (Assets = Liabilities + Equity), `calculation` and `calculation_filing` (XBRL calc linkbase parent ≈ Σ children × weight), `dqc_cf_sign` and `dqc_0015_never_negative` (XBRL US Data Quality Committee sign rules). A calculation `error` means the check could not reconcile the parent with the child values as Hub-Equity extracted them. It is NOT a finding that the issuer's statements are wrong: report it as an unreconciled check, and open the filing before drawing any conclusion about the company. Default `status_filter` = ["warning", "error"]. Provide ["valid","skipped"] to also see silent successes. Provide at least one of `filing_id` or `entity_id`. Returns sorted by severity desc then |relative_difference| desc, capped at 100 rows. Use when the user asks "did the balance sheet balance?" / "which totals of this filing does the check fail to reconcile?".

List the catalog of standardized Hub-Equity hubs. Useful when you need to enumerate available metrics for a category (e.g. all balance-sheet hubs) without making N search_concept calls. Args: category: One of income_statement, balance_sheet, cash_flow, ratio, equity_info, metadata. Omit to list across all categories. include_non_primary: True to include derived/secondary hubs. limit: Cap (max 200, default 80).

Rebuild a figure from the components this issuer reported when the figure itself is not tagged. Use when get_fact finds nothing for an aggregate. Below a paid plan the value comes without `algorithm` and `contributions`.

Filter the Hub-Equity universe by metadata + revenue + audit + data quality criteria. Use this when the user wants a LIST of companies matching criteria, not a single company. Examples: "European tech companies with revenue > 1B", "US Big 4 audited firms with quality grade >= B". `min_revenue`/`max_revenue` are in USD (ECB spot rate); an entity whose currency has no current rate is left out of a revenue filter. `country` is ISO-2 ('US', 'FR', ...). `revenue_year` keeps the entities whose latest reported revenue year is N (not the revenue of fiscal year N for every entity). `min_quality_grade` ∈ {A+, A, B, C, D}. `sort_by` ∈ {revenue_desc, revenue_asc, employees_desc, employees_asc, quality_desc, name_asc}.

Search Hub-Equity standardized hub concepts by code or label. Returns up to 10 matches. Use this when you don't know the exact `hub_concept_code`. Accepts plain English ('Costs and Expenses') and bare hub codes ('TOTAL_ASSETS').