Handelsregister

    Parameters:
    - company_id (required): "AT:{fnr}" (bare FNR accepted). Austria only (needs parsed
      financials); a German id returns a clear error.
    - n (optional, default 10): how many nearest peers to return.

    Returns the AT backend's benchmark payload plus ``country`` and the prefixed
    ``company_id``: headline figures, ``percentiles`` within the UGB size class, and the
    nearest peers with a recency note. For a cross-border meaning-based peer set use
    find_peers with cross_border=true.

    Parameters:
    - country (optional, default "all"): "AT" | "DE" | "all" - whose field catalogs to
      include.

    Returns {id_scheme, capabilities, countries, countries_unavailable}. ``id_scheme``
    documents the unified company_id ("AT:123456a", "DE:D2601_HRB135076"; bare national
    ids are accepted, responses always return the prefixed form). ``capabilities`` is
    the per-country capability matrix including each country's supported unified
    filters - a filter absent for a country is applied to the others and reported in a
    notice, never silently dropped. ``countries`` carries each backend's own
    describe_fields payload (code tables, null rules, tool tiers). Call once up front
    when unsure which filter or tool to use; it returns no company data itself.

    Parameters:
    - filters (optional): EXACTLY the same unified filters as search_companies.
    - sort (optional): same as search_companies (applies where the country supports
      the field).
    - max_rows (optional, default 1000, max 10000): per-country row ceiling.
    - country (optional, default "all"): "AT" | "DE" | "all".

    Returns {countries: {<code>: {download_url, rows, columns, ...}}, notices}. ONE
    CSV per country (semicolon-separated, UTF-8 BOM, Excel-ready): each register
    exports its own column set - DE files have no financial columns yet (blank would
    wrongly read as zero). Download links are signed and valid ~60 minutes. A filter a
    country does not support excludes that country with a notice, like
    search_companies. For browsing/ranking on screen use search_companies instead.

    Parameters:
    - company_id (required): "AT:{fnr}" or "DE:{court}_{type}{number}" (bare national
      ids accepted), from a search card.
    - n (optional, default 10): how many peers per country.
    - cross_border (optional, default false): when true, additionally returns
      ``peers_abroad`` - the companies in the OTHER country whose registered purpose
      is semantically closest to the reference company's activity text.

    Returns {company_id, country, peers_home, home_envelope, peers_abroad?, notes}.
    ``peers_home`` uses the home register's own peer logic (AT: same size class,
    same industry preferred, nearest by Bilanzsumme; DE: semantic-first by registered
    purpose). ``peers_abroad`` is a MEANING-based match, not a size or financial
    benchmark - the honest cross-border comparison given the countries' different
    data depth (see notes). Empty peers_home means the id is unknown or the company
    lacks the data its register ranks by. For a strict filtered list use
    search_companies; for aggregates use the country server's cohort tools.

    Parameters:
    - dimension (required): "gkl" (UGB size class, AT only), "bundesland", or
      "legal_form" (alias size_gkl -> gkl).
    - value (required): the cohort value (e.g. bundesland "Wien", legal_form "GmbH").
    - country (optional, default "all"): "AT" | "DE" | "all".

    Returns {countries, dimension, value, per_country, notices}. ``bundesland`` and
    ``legal_form`` fan out to every supporting country; ``gkl`` is Austrian-only (no German
    size-class facet) and excludes DE with a notice. Each country's own cohort payload sits
    under ``per_country`` (the registers aggregate different metrics, so they are reported
    side by side, not force-merged). For one company use get_company_details; for a filtered
    list use search_companies.

    Parameters:
    - company_id (required): "AT:{fnr}" (e.g. "AT:123456a") or
      "DE:{court}_{type}{number}" (e.g. "DE:D2601_HRB135076"); bare national ids are
      accepted too. Take it from a search card's ``company_id``.
    - max_signatories (optional, DE only): cap on the served officer list (DE default
      15, 0 = all); ignored for AT.

    Returns the country backend's full profile plus ``country`` and the prefixed
    ``company_id``. AT: identity, location, per-year Bilanz + GuV, ratios, growth,
    filings, management, events. DE: identity, seat, Stammkapital, Gegenstand, WZ/NACE
    classification, managing directors (birth year only), and the parsed
    Jahresabschluss (Bilanz, ratios, GuV where published) for companies the rollout
    has reached - ``financials.reporting_status`` says whether figures exist, the
    source publishes none, or the company has not been processed yet, so never report
    missing German figures as zero. Unknown id ->
    {error: not_found}. Use search_companies first when you only have a name.

    Parameters:
    - company_id (required): "AT:{fnr}" or "DE:{court}_{type}{number}" (bare national ids
      accepted), from a search card.
    - metrics (optional, AT only): names of the metrics to return (e.g. bilanzsumme,
      umsatzerloese, equity_ratio); omitted = all. Ignored for DE.

    Returns the backend's history payload plus ``country`` and the prefixed
    ``company_id``: per-metric {year: value} with latest/latest_year. AT serves the parsed
    Bilanz/GuV/ratio series. DE serves the parsed Jahresabschluss series where the company
    has filed and its Bundesland is loaded; an empty series means not-filed or not-yet-
    loaded, never zero (see get_company_details financials.reporting_status). For a single
    snapshot use get_company_details; for the complete record use get_full_record.

    Parameters:
    - country (optional, default "all"): "AT" | "DE" | "all" - which countries to include.

    Returns {countries: {<code>: <that backend's coverage payload>}, capabilities,
    countries_unavailable}. Each country section is the country backend's own coverage
    dashboard (AT: parsed-financials counts by format/status; DE: per-Bundesland counts
    + fill rates - the DE backfill is still running, so a low count means "not crawled
    yet", not "does not exist"). ``capabilities`` is the machine-readable matrix of what
    each country supports (financials, documents, events windows, filters); a country
    that cannot be reached appears under ``countries_unavailable`` with the error
    instead of failing the whole call. For valid filter values use describe_fields;
    for per-company data use search_companies.

    The two registers address a document differently, so the parameters differ by country —
    pass the shape that matches the id:

    **Germany** -- company_id + kind:
    - company_id: "DE:{court}_{type}{number}" (e.g. "DE:D2601_HRB135076"); a bare German id
      works too.
    - kind: "AD" = Aktueller Abdruck (current register extract, default), "CD" =
      Chronologischer Abdruck -- the official Handelsregister abstract PDF; or "JA" =
      Jahresabschluss -- the newest official annual financial statement as published by the
      Unternehmensregister (served as the official HTML document, no PDF exists at the
      source). AD/CD are fetched from handelsregister.de on demand (first call ~10 s, then
      cached); JA comes from the stored publication.

    **Austria** -- a FILING, because the Austrian register holds no abstract document type:
    its official document IS the annual filing, identified by its Stichtag.
    - document_ref: "{fnr}:{stichtag}" exactly as list_documents returns it (e.g.
      "118977t:2025-01-31"), or
    - company_id: "AT:{fnr}" (bare FNR accepted) for the company's LATEST filing.
    - kind does not apply and is ignored; a German kind with an Austrian id is an error that
      names list_documents instead.

    Returns a short-lived download link to the original artifact plus availability. When the
    register holds nothing for that kind/Stichtag, ``available`` is false with a ``note``
    (never a dead link). Both countries carry ``country`` and the prefixed ``company_id``.
    For the Austrian filing's extracted TEXT (Anhang, Lagebericht) use get_document_text.

    Parameters:
    - doc_key (required): the document_ref from list_documents (an Austrian filing key).
    - max_chars (optional, default 40000, clamped 1000-120000): size of ONE window.
    - offset (optional, default 0): character position the window starts at. To read a long
      filing, call again with offset = the previous response's ``next_offset`` until
      ``has_more`` is false; ``chars`` is the document's total length. Without offset the tail
      of a filing -- where the Anhang sits -- is unreachable at any cap.

    Returns {doc_key, text, chars, offset, returned_chars, next_offset, has_more, ...} with
    the filing's Stichtag for citation. ``attachments`` lists the documents embedded in the
    filing (Anhang, Lagebericht, Bestaetigungsvermerk) with their page count and whether their
    text could be extracted -- a scanned Anhang says so instead of answering empty, and when
    nothing can be extracted ``note`` explains why. Austria only today. Use list_documents to
    discover the key, get_document for the original artifact.

    Parameters (all optional): since / until (default last 30 days); bundesland;
    nace_section; nace_division (AT); legal_form (AT); country ("AT" | "DE" | "all").

    Returns {countries, per_country, windows, notices}, each country's block being its
    own {total, by_type, by_bundesland}. Only AT exposes event statistics today; DE is
    reported in notices as not yet available (never as zero). For the individual
    changes use list_events.

    Parameters:
    - company_id (required): "AT:{fnr}" (bare FNR accepted). Austria only today; a German
      id returns a clear error (Germany does not serve a full parsed record yet).

    Returns the AT backend's full-record payload plus ``country`` and the prefixed
    ``company_id``. Includes unknown-code passthrough and the filing years covered.

    Parameters:
    - window (optional, default "today"): "today" | "yesterday" | "month_to_date" |
      "last_30_days" | "all".

    Returns only the calling key's own usage (totals + per-tool breakdown) for that
    window - never another user's data and never the email behind the key. One meter
    spans AT and DE, since the facade is the single billing point. Use it to check your
    consumption against the plan's rate limits.

    Parameters:
    - company_id (required): "AT:{fnr}" (bare FNR accepted). Austria only; Germany serves no
      filing chronology -- for the German register abstract call get_document with a "DE:" id.

    Returns the AT backend's document list plus ``country`` and the prefixed
    ``company_id``: each entry has type, Stichtag, financial_year, document_ref, format and
    whether it was parsed. Feed a document_ref to get_document for the original signed PDF/XML,
    or to get_document_text for the extracted text.

    Parameters (all optional, AND-combined):
    - types: any of the SUPERSET enum - founding, new_registration, deletion,
      deletion_announced, name_change, seat_change, legal_form_change, capital_change,
      management_change, management_join, management_leave, gegenstand_change, merger,
      split, conversion, contribution, consolidation, division,
      shareholder_capital_change. Each country's feed carries a SUBSET; a type not in
      a country's feed is skipped for that country (reported in notices), and a
      country with none of the requested types is excluded. Note new_registration (DE,
      a discovery date) and founding (AT, a register event) are distinct - see
      describe_fields.
    - since / until: ISO dates. Default window: last 30 days.
    - bundesland: full state name.
    - nace_section (A-U, both countries); nace_division (AT only); legal_form (AT only).
    - company_ids: prefixed watchlist; AT filters the whole list, DE filters ONE id at
      a time (pass a single DE id, or query DE separately).
    - country: "AT" | "DE" | "all" (default). page (1), page_size (25).

    Returns {countries, events, per_country, windows, notices}. ``events`` are merged
    newest-first, each with ``country`` and a prefixed ``company_id``; AT events add
    before/after values only for the detailed types. ``windows`` states each country's
    data availability (AT: detailed >= 2026-07-01, coarse >= ~2020; DE: >= 2026-07-30)
    so an empty stretch is never mistaken for missing data. For aggregate counts use
    get_event_stats; for one company's history use get_company_details.

    Parameters:
    - query (optional): a category word (e.g. "Brauerei", "software"); returns ``matches``
      with each sector's level, code, label and the nace_* filter value for search_companies.
      Omitted: the legal-form and size-class value lists with counts.

    Served from the Austrian backend; the industry codes are OENACE == WZ == NACE Rev. 2,
    identical for both countries, so a resolved code also filters the German register. The
    value lists and counts themselves are Austrian (a notice says so). It returns no company
    data - call it once up front to resolve a filter value.

    Parameters:
    - check_backends (optional, default false): when true, additionally performs a
      cheap connection handshake against every configured country backend and reports
      per-country reachability ("ok" / "unreachable").

    Returns {status, server, countries, provenance} - countries maps each configured
    country code to its backend product name and, with check_backends, its live
    reachability. Use get_coverage for data completeness; this tool only says whether
    the service is up.

    Parameters:
    - filters (optional): every field optional, AND-combined. Shared core (both
      countries): name (substring), query (MEANING-based hybrid search over the
      registered purpose - both countries), status (active|inactive|all, default all),
      legal_form, bundesland, city, postal_code (prefix; AT PLZ 4-digit, DE 5-digit),
      near {place | postal_code, radius_km} (radius search, matches from EVERY queried
      country within the radius - works across the border), nace_section (A-U; OENACE
      == WZ == NACE Rev. 2, so one industry code filters both countries), gegenstand
      (literal substring over the registered activity text), manager_name (person
      search), company_ids (prefixed watchlist, e.g. ["AT:123456a",
      "DE:D2601_HRB135076"], max 100), nace_division/group/class, founded_year_min/max,
      and the balance-sheet screens size_gkl (AT W/K/M/G or DE kleinst/klein/mittel/
      gross, translated per register), bilanzsumme_min/max, equity_ratio_min/max
      (fraction, 0.35 = 35 %), has_guv, growth_profile - in Germany these match only
      companies with a parsed Jahresabschluss (rollout per Bundesland, see
      get_coverage; a notice states the scope). AT-only today (see describe_fields
      capabilities): revenue/employees ranges, has_guv_latest, last_filing_year_min,
      gf_age_min, event_signal/since/until. DE-only: registergericht, capital_min/max
      (Stammkapital). Country aliases (geschaeftszweig, oenace_*, wz_section, fnrs,
      stammkapital_*) are accepted.
    - sort (optional): {field, descending}. AT fields: bilanzsumme (default), revenue,
      equity_ratio, employees, last_filing_year, revenue_growth_1y/3y/5y, distance.
      DE fields: name, register_nummer, capital, bilanzsumme, equity_ratio, revenue
      (financial sorts rank the companies with figures first). A country that cannot
      sort by the requested field returns its default order (reported in notices).
    - page (default 1), page_size (default 25).
    - after (optional): KEYSET paging for bulk extraction - single country only
      (cursors are per register). Pass "" to start, then the country's next_after
      from per_country.
    - exact_count (optional, default false): force exact totals (costs a full scan).
    - country (optional, default "all"): "AT" | "DE" | "all".

    Returns {countries, total: {AT, DE, combined}, results, per_country, notices}.
    ``results`` are compact cards, each with ``country`` and the prefixed
    ``company_id``; with country="all" the list is AT block then DE block - each
    country keeps its own ranking (no fake interleave). ``per_country`` carries each
    register's own envelope (exact totals or lower bounds, applied_filters,
    relaxations on zero hits, query_mode, next_after). A filter one country does not
    support excludes that country and says so in ``notices`` - it is never silently
    dropped; an unreachable backend appears in ``countries_unavailable`` instead of
    failing the call. Never report a German company's financials as zero - the German
    Jahresabschluss rollout is per Bundesland, so a company without figures has not
    been processed yet or files none (see get_coverage and
    financials.reporting_status in get_company_details).

    For one company's full profile use get_company_details; for a downloadable list
    use export_companies_csv; for dataset completeness use get_coverage.

    Parameters:
    - name (required): person name substring, case-insensitive, e.g. "Mustermann".
    - country (optional, default "all"): "AT" | "DE" | "all".
    - page_size (optional, default 25): results per country.
    - status (optional, default "all"): "active" | "inactive" | "all".

    Returns the merged search_companies envelope ({countries, results, per_country,
    notices}) plus ``person_query``; every result card carries ``country``,
    ``company_id`` and the matched manager. AT matches the primary managing director,
    DE matches all managing directors AND registered signatories. IMPORTANT: matching
    is by name and the registers publish birth YEAR only - a shared name across
    companies or countries does not prove the same person (the notice says so; use
    birth years and context to corroborate). For general company search use
    search_companies with other filters; manager_name can be combined there too.