Carbon Arc

Convert natural language questions into analytical results from Carbon Arc's own data platform. All answers are computed from data that Carbon Arc has already ingested and hosts internally. This tool does not browse the web, call third-party APIs, or fetch documents at query time. Returns markdown tables for quantitative insight metrics (card spend, foot traffic, rankings, trends) from Carbon Arc's licensed data panels. Returns narrative analysis with source citations from Carbon Arc's internal document archive, a pre-ingested, Carbon Arc-hosted collection of SEC filings (10-K/10-Q), earnings call transcripts, company and market news articles, and bull/bear investment theses. Coverage is limited to what has been ingested into that archive. **Query shapes supported (structured analytics):** - **timeseries** — metric values grouped by date (default); e.g., "Show Walmart card spend over 2024" - **summary** — single aggregate per entity with no date grouping; e.g., "Total card spend by company in Q1 2024" - **list** — distinct entity or dimension values matching filters; e.g., "What platforms had advertising spend for Walmart in 2024?" - **ranking** — top-N leaderboard across entities; e.g., "Top 10 companies by card spend last year", "Which brands had the highest revenue in 2024?" - **ranking_timeseries** — top-N entity discovery followed by a full timeseries for each; e.g., "Show card spend trends for the top 5 retailers" **Common Use Cases:** - Revenue and spend analysis by company, region, or time period - Growth metrics and trend analysis - Comparative analysis across entities and insights - Management commentary, risk factors, filing narrative, news in Carbon Arc's archive, and bull/bear investment-case questions - Top-N leaderboards and ranking across entities (ranking / ranking_timeseries shapes) - Aggregate summaries without time grouping (summary shape) - Distinct-value lookups for entities or dimensions (list shape) **Not Suitable For:** - Schema/metadata discovery: "What data is available for Walmart?", "What fields can I filter on?" - Vague or incomplete questions with no metric/insight and no document angle (e.g., "walmart 2025", stock predictions, unknowable private facts) - Questions that don't reference a specific data metric, statistic, quantity, or document topic (filings, earnings calls, news in Carbon Arc's archive, investment theses) - Named events (earnings, Fed decisions, conferences, etc.): this tool does not resolve or query events. Discover with search_events (or get_events_from_entity / get_events_from_insight), then execute via framework_to_insight with events (event_type plus event_id and/or event_category_id). This tool requires a question that references a specific data metric or insight (e.g., card spend, box office revenue, website traffic), or a question about SEC filings, earnings calls, news in Carbon Arc's archive, or bull/bear investment theses. Questions with only an entity name but no metric may return an error with recovery suggestions. If the user's question lacks a clear metric or document angle, ask them what specific data they want before calling this tool.

text_to_insight

Search and describe datasets in the CarbonArc data library. Use this tool for dataset discovery and provenance questions: - "What data do you have about card spend?" - "Where does this data come from?" - "What fields are available in the retail foot traffic dataset?" **Routing:** - Any ID provided (insight_id, topic_id, dataset_id) → describe mode: returns the full TearSheet for that dataset, including provider, frequency, history, delivery method, panel size, coverage, bias, lag, geographic availability, data dictionary, raw `tearsheet_data` metadata, and last refresh date. - Only query provided → search mode: semantic search over datasets by name/description. - No arguments → catalog overview: returns the full accessible TearSheet catalog (subject to source access restrictions). **Search then describe:** Call with a query first to find relevant datasets, then pass the `tearsheet_name` from any search result as `dataset_id` to retrieve its full TearSheet details. **This tool vs search_insights:** - Use `data_library` for dataset/provenance questions (what data exists, what fields, where does it come from, how is it collected). - Use `search_insights` for metric discovery (finding specific analytical insights/KPIs to use in framework queries).

data_library

Convert structured analytical frameworks into insights. This tool takes a pre-defined analytical framework (structured query parameters) and executes it to generate insights. Useful when you have specific query parameters rather than natural language questions. This provides more control than natural language queries and is ideal for programmatic access or when you know exactly what data structure you need.

framework_to_insight

Get entities linked to a specific event. Retrieves entities associated with a particular parent event (e.g. companies for a corporate filing). Use search_events first to resolve an event name to its event_id and event_type.

get_entities_from_event

Get entities related to a specific insight. Retrieves entities associated with a particular insight. Useful for exploring what entities are involved in a specific insight or understanding insight-entity relationships. Entities are listed by association, not ranked by any metric. Valid entity_representation values: abundle, actor, aingredient, app, apublisher, artist, bullbearargument, category, cbsa, city, clfiling, clopinion, comcategory, company, country, court, dccategory, ddcategory, director, distributor, dma, docket, dtcategory, educationlevel, entertainer, ethnicity, finished, franchise, gender, generation, genre, judge, label, lawyer, league, legalmatter, maritalstatus, medicalsegment, mine, newsarticle, occupation, pcodecategory, plabel, platform, port, product, quailinvoice, quailmatter, raw, region, retailer, secfiling10k, secfiling10q, service, socialhandle, song, sport, state, team, ticker, title, transcript, transformed, us, vehiclebody, vehiclemake, vehiclemodel, venue, website, ww, yearlyincome, zip

get_entities_from_insight

Get events linked to a specific entity. Retrieves events associated with a particular entity through shared insights. Useful for discovering which events are connected to a given company or entity. Use search_entities first to resolve an entity name to its entity_id.

get_events_from_entity

Get events linked to a specific insight. Retrieves events associated with a particular insight node. Useful for discovering which events are connected to a given insight. Use search_insights first to resolve an insight name to its insight_id.

get_events_from_insight

Discover available filters for a framework, or fetch selectable values for a specific filter. **Metadata mode** (filter_key omitted): Returns all available filters for the given entity/insight combination. Each item's ``filter_key`` is the identifier to use in step 2 and in ``framework_to_insight`` filters. ``label`` is human-readable display text only. No SQL is executed — this is a fast, free discovery call. **Values mode** (filter_key provided): Returns distinct selectable values for the specified filter. Each option's ``value`` is what to pass in ``framework_to_insight`` filters or ``dependency_filters``. ``label`` is human-readable display text only. **Typical workflow:** 1. Call without ``filter_key`` to learn which filters are available. 2. For each filter you want to populate, call again with ``filter_key`` set to the ``filter_key`` returned in step 1. 3. Pass the selected ``value``(s) into ``framework_to_insight`` as ``filters``: e.g. ``{"state": ["California", "Texas"]}``.

get_filter_options

Get insights related to a specific entity. Retrieves insights associated with a particular entity (e.g., company, state, retailer). Useful for exploring what data is available for a specific entity or understanding entity-insight relationships. Valid entity_representation values: abundle, actor, aingredient, app, apublisher, artist, bullbearargument, category, cbsa, city, clfiling, clopinion, comcategory, company, country, court, dccategory, ddcategory, director, distributor, dma, docket, dtcategory, educationlevel, entertainer, ethnicity, finished, franchise, gender, generation, genre, judge, label, lawyer, league, legalmatter, maritalstatus, medicalsegment, mine, newsarticle, occupation, pcodecategory, plabel, platform, port, product, quailinvoice, quailmatter, raw, region, retailer, secfiling10k, secfiling10q, service, socialhandle, song, sport, state, team, ticker, title, transcript, transformed, us, vehiclebody, vehiclemake, vehiclemodel, venue, website, ww, yearlyincome, zip

get_insights_from_entity

Get insights linked to a specific event. Retrieves insights associated with a particular event node. Useful for exploring what data is available for a specific event or understanding event-insight relationships. Use search_events first to resolve an event name to its event_id and event_type.

get_insights_from_event