RoboSystems

View saved version →

---
name: sec-filing-analysis
description: >-
  Analyze a public company from its SEC EDGAR XBRL filings on the RoboSystems `sec`
  graph — statements by ticker or CIK, cross-period and cross-company metric
  comparisons, concept-to-element resolution, and full-text search over 10-K/10-Q
  narrative. Use for questions like "show me NVIDIA's income statement", "compare
  gross margin across the last eight quarters", "which filers mention goodwill
  impairment", or any request that names a ticker, CIK, 10-K, 10-Q, or XBRL concept.
---

# SEC filing analysis on the `sec` graph

The `sec` graph is a curated, read-only knowledge graph of public-company XBRL
filings. There is no general ledger here and nothing to write; every tool is an
analytical read. Rate limits apply per plan, so prefer one well-chosen call over
many exploratory ones.

## The ladder — cheapest tool that answers

1. **`financial-statement-analysis`** — a whole statement for one company.
   `ticker` is required on `sec`; `statement_type` is `income_statement`,
   `balance_sheet`, `cash_flow_statement` or `equity_statement`. Without
   `report_id` it auto-resolves the latest matching filing (`period_type`
   `annual` → 10-K/20-F/40-F; `quarterly` → 10-Q; `instant` for balance-sheet
   facts). Returns deduplicated consolidated facts ordered by period, plus the
   `resolved_report`. Start here for "show me X's statement".
2. **`build-fact-grid`** — *specific* elements across any mix of periods and
   entities. Use `canonical_concepts` (`revenue`, `net_income`, `total_assets`,
   …) rather than raw qnames so cross-filer tagging differences collapse
   (`us-gaap:Revenues` vs `us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax`).
   Set `period_type` for duration concepts, `entities` for multi-company
   comparisons, and raise `limit` when `truncated` comes back true. This is the
   tool for "compare A and B" and "trend over N periods".
3. **`resolve-element`** — map a concept in words to the qnames actually used,
   with fact counts and a ready-to-run `query_hint`. Call it before writing
   Cypher that filters on an element.
4. **`search-documents`** — BM25 keyword search across filing narrative and
   iXBRL disclosure sections; `semantic: true` adds vector ranking. Filter with
   `entity`, `form_type`, `fiscal_year`, `section` (`item_1a`, `item_7`, …) or
   `element` (find disclosures carrying a given XBRL fact). Follow a hit with
   **`get-document-section`** for the full text; iXBRL hits carry
   `xbrl_elements` you can hand to `resolve-element` — the bridge from narrative
   back to numbers.
5. **`read-graph-cypher`** — when the shaped tools don't fit. Always run
   `get-example-queries` first; the patterns below are the ones that matter.

## Cypher patterns that work here

Consolidated revenue for one company, cross-filer robust:

```cypher
MATCH (f:Fact {has_dimensions: false})-[:FACT_HAS_ELEMENT]->(e:Element),
      (f)-[:FACT_HAS_ENTITY]->(ent:Entity {ticker: 'NVDA'}),
      (f)-[:FACT_HAS_PERIOD]->(p:Period {duration_type: 'annual'})
WHERE e.canonical_concept = 'revenue' AND f.numeric_value IS NOT NULL
RETURN ent.ticker, e.qname, p.end_date, f.numeric_value AS revenue
ORDER BY p.end_date DESC LIMIT 10
```

A whole statement via the presentation structure — anchor on the entity, reach
`Structure` last:

```cypher
MATCH (ent:Entity {ticker: 'NVDA'})<-[:FACT_HAS_ENTITY]-(f:Fact {has_dimensions: false})-[:FACT_HAS_ELEMENT]->(e:Element),
      (f)-[:FACT_HAS_PERIOD]->(p:Period {duration_type: 'annual'}),
      (fs:FactSet)-[:FACT_SET_CONTAINS_FACT]->(f),
      (s:Structure {canonical_type: 'income_statement'})-[:STRUCTURE_HAS_FACT_SET]->(fs)
WHERE f.numeric_value IS NOT NULL
RETURN DISTINCT e.qname, f.numeric_value AS value, p.end_date
ORDER BY p.end_date DESC LIMIT 40
```

Segment breakdowns — flip the dimension flag:

```cypher
MATCH (f:Fact {has_dimensions: true})-[:FACT_HAS_ELEMENT]->(e:Element),
      (f)-[:FACT_HAS_DIMENSION]->(d:Dimension)
WHERE e.q

Preview of the first 4,000 characters. Read full instructions →