RoboSystems

Construct multidimensional fact grid from graph data. Retrieves facts based on elements, periods, and optional dimensions. Returns structured data with element names, values, and periods. Use include_summary=true to add per-element statistics: count, min, max for every element, plus total and average for duration elements only — a balance summed or averaged across periods is not a balance, so instants (e.g. total_assets) omit both. **WHEN TO USE:** - When the user asks to compare specific financial metrics across periods or companies - To build custom cross-company comparisons (e.g., "compare NVDA and AAPL total assets") - When you need precise control over which elements, periods, and entities to include - For ad-hoc financial analysis that doesn't fit a standard statement format **HOW IT DIFFERS FROM financial-statement-analysis / live-financial-statement:** - financial-statement-analysis returns ALL line items for a standard statement from the graph-backed XBRL hypercube (SEC or materialized tenant) - live-financial-statement returns ALL line items for a standard statement from the tenant's live OLTP ledger - build-fact-grid returns SPECIFIC elements you choose, across any combination of periods and entities **PARAMETERS:** - elements: XBRL qnames (e.g., 'us-gaap:Assets'). Use resolve-element to find qnames. - canonical_concepts: Normalized concept names (e.g., 'revenue', 'net_income'). Matches ALL element qnames mapped to each concept across companies. Can be combined with elements. - periods: End dates in YYYY-MM-DD format - entity/entities: Filter by ticker, CIK, or name. Use 'entities' array for multi-company. - period_type: 'annual', 'quarterly', or 'instant'. Important for duration elements (revenue, net income). - form: SEC filing type ('10-K', '10-Q') - fiscal_year/fiscal_period: Filter by report fiscal context **RETURNS:** - Deduplicated facts with element qnames, names, values, periods, units, and entity ticker/name — one record per fact, not a pivot table - Only consolidated totals (dimensional breakdowns excluded) - `truncated: true` when more facts matched than `limit` allowed; the ones returned are the most recent by period - A figure a filer reports in two units (its own currency and a US-dollar translation) comes back once per unit, and `units_note` says so — never put two units in one series **NOTES:** On shared repositories (e.g. SEC) entity or entities is REQUIRED — those graphs host thousands of filers, so an unscoped query returns an arbitrary slice of arbitrary companies. On a tenant graph the URL already scopes to one entity, so the filter is optional there. On a tenant graph select by `elements` with `periods` or `period_type`: `canonical_concepts`, `form`, `fiscal_year` and `fiscal_period` exist only on shared repositories and are refused there rather than answered with nothing. For income statement items (revenue, net income), always specify period_type='annual' or 'quarterly' to avoid mixing duration types. Use canonical_concepts for cross-company comparisons where companies may use different XBRL tags for the same concept.

build-fact-grid

How one filing is laid out: entity, periods, statements and disclosures by role, axes, and the text — its Items (10-K / 10-Q) and largest text blocks with the character `offset` each starts at, which `read-text` pages from. Call it before `read-text` when you want a whole section rather than a match. **WHEN TO USE:** - Before reading a whole Item (MD&A, Risk Factors) with `read-text`: its offset is here - To see what a filing is — form, dates, an 8-K's items — before searching it **PARAMETERS:** - `ticker` — on SEC, the filer: its latest annual report unless `fiscal_year` / `period_type` / `accession` / `form` say otherwise; any processed year reads - `form: "8-K"` — the latest earnings release, or with `fiscal_year` the latest filed in that calendar year; `accession` — one filing (a report, or an 8-K from `recent_releases`) - `report_id` — a report in the SEC graph, on its own (not beside a ticker) **RETURNS:** - `profile.text` — "primary document" when the filing's own document is read, "tagged text blocks" when its folder holds none - `filing` (form, dates, `items` on an 8-K), `entity`, `counts`, `periods`, `statements`, `disclosures`, `axes` - `sections.items` — each Item's `id`, `label`, `offset`, `chars`; `sections.text_blocks` — the largest blocks - `resolved_report.links` on SEC — `viewer` opens the filing in the xbrlkit viewer (give the user that URL to show it), `holon`, `tavi`, `as_filed`, an 8-K's `exhibits`, `edgar` **RELATED TOOLS:** - `search-text` — find words inside this filing; `read-text` — page it from an offset - `disclosures` / `information-block` — a section's facts, breakdowns and footing

describe-filing

The map of a report's sections: one row per disclosure family — a note with its policies, tables and details, a statement with its parenthetical, the cover page — with block counts by level, fact counts and text-block counts, in filing order. With `topic`, one family's blocks: each block's id, level, name, fact count, axes and text blocks. Cheap. Call it first, then `information-block` for the one block you need. **WHEN TO USE:** - "What does this filing disclose about leases / debt / segments / taxes?" — the map, then the family - Before `information-block`: to find the block id - To see which sections carry dimensional breakdowns (`dimensional_facts`) or text blocks **PARAMETERS:** - `ticker` / `report_id` — which one is required depends on the graph: SEC needs `ticker` (auto-resolves the latest 10-K; `fiscal_year` and `period_type` narrow it) or a `report_id`; a tenant graph needs `report_id` - `topic` — a family's name, or part of it ("leases", "income taxes"); omit for the whole map **RETURNS:** - Without `topic`: `disclosures` — one row per family: `disclosure`, `blocks`, `levels` (note / policies / tables / details / statement / parenthetical / document), `facts`, `text_blocks`, and `category` when the family is not a note - With `topic`: `blocks` — each with `id` (what `information-block` takes), `level`, `name`, `facts`, `dimensional_facts`, `axes`, `has_calc`, `text_blocks` - `resolved_report` when the report was resolved from a ticker, with `links` on SEC: `viewer` opens the filing in the xbrlkit viewer — give the user that URL to show the filing — beside `holon`, `tavi`, `edgar` **NOTES:** - Families are read off the filer's own role titles, so the map is the filing's complete section index — statements and the cover page included - The whole map is a few thousand characters; one family about 1.5K. `information-block` is the expensive call, so narrow here first - The same tool `xbrlkit serve` offers over a loaded filing: same name, same shape **RELATED TOOLS:** - `information-block` — one block read whole - `financial-statement-analysis` — the primary statements as flat fact rows - `get-information-block` / `list-information-blocks` (tenant graphs) — one authored block's envelope, with its rules and verification; this tool maps the report's sections as the ledger holds them

disclosures

Return a structured financial statement from the graph-backed XBRL hypercube. **WHEN TO USE:** - SEC shared repository: "show me NVDA's latest 10-K income statement" - RoboLedger tenant graph post-materialization: historical analytical queries against the materialized ledger - Use when you want cross-period or cross-entity analytical views rather than the current live books (use live-financial-statement for the latter) **NOTES:** - Shared-repo (SEC): `ticker` REQUIRED. If no `report_id`, auto-resolves the latest matching filing by form type (10-K/10-Q/20-F/40-F). - Tenant graph: `report_id` REQUIRED. **PARAMETERS:** - `statement_type` (required) — one of income_statement, balance_sheet, cash_flow_statement, equity_statement - `period_type` — annual (10-K/20-F/40-F, duration facts), quarterly (10-Q plus annuals for international filers, duration facts), or instant (point-in-time facts; the balance-sheet default). Unset on an annual form it defaults to annual, so a 10-K's quarterly note figures stay out - `periods` — how many period end dates to keep, newest first (default 2 for the balance sheet, 3 for the flow statements — the columns a filing presents). Raise it for a longer series - `ticker` / `report_id` — which one is required depends on the graph; see NOTES **RETURNS:** - Deduplicated facts (canonical_concept, qname, value, unit, start_date / end_date, period_type, duration_type; null fields omitted; `name` only when it is a label rather than the qname's local part) ordered by end_date DESC - A line a filer reports in two units (its own currency and a US-dollar translation) comes back once per unit, and `units_note` says so — read one unit down the statement, never a mix - `periods` — the period keys the facts span, newest first, and `periods_omitted` when older end dates were cut by the cap - resolved_report info when auto-resolution was used, with `links` on a shared repository: `viewer` opens the filing in the xbrlkit viewer — give the user that URL to show the filing — beside `holon`, `tavi`, `edgar` - Dimensional/segment breakdowns are filtered out (consolidated totals only)

financial-statement-analysis

Read a document section by ID, a window at a time. Use this after search-documents to read the text behind a hit before answering from it. **WHEN TO USE:** - After search-documents returns results, use the document_id from a hit to read the section - When you need the text of an MD&A, risk factor, or business description - To read the full context around a search snippet **PARAMETERS:** - `document_id` (required) — from a search-documents hit, or the next_document_id of a part - `offset` — character offset to start from (default 0) - `length` — characters to return (default 4000, max 8000) **RETURNS:** - `content` — the requested window. `content_length` is the whole part, and `next_offset` is present when more of it follows: call again with it as `offset` to read on rather than answering from a partial read - Entity, filing, and section metadata - A long section is stored in parts of about 25K characters: the result is one part (part of part_count, section_label like "MD&A (2/6)") and carries next_document_id — call again with it to read the next part; parent_document_id is shared by the section's parts - content_url for the CDN-hosted clean text (when available) - For iXBRL disclosures: xbrl_elements, the XBRL fact tags in this section — use resolve-element or read-graph-cypher to cross-reference with the knowledge graph

get-document-section

Get example Cypher queries for this graph database. **WHEN TO USE:** - When starting to explore a new graph - When you need query patterns for specific node types - When learning the relationship structure - After getting errors to see correct syntax **RETURNS:** List of example queries with explanations, tailored to the actual schema present in this graph. **NOTES:** - The examples are real working queries for this specific graph, so they carry its actual property names and relationships - Copy and modify them rather than writing a traversal from scratch **⚠️ QUERY PATTERN NOTE:** When joining multiple relationships from the same node, use comma-separated patterns in a SINGLE MATCH clause (not multiple MATCH clauses): - ✅ GOOD: `MATCH (f:Fact)-[:R1]->(a), (f)-[:R2]->(b)` - ❌ BAD: `MATCH (f:Fact)-[:R1]->(a) MATCH (f)-[:R2]->(b)` (may timeout) **📅 PERIOD.period_type VALUES:** Period nodes classify time context into three types: - `instant` - Point-in-time (balance sheet dates) - `duration` - A date range (income statement periods) — use `duration_type` for subtype - `forever` - Unbounded period (rare) **📅 PERIOD.duration_type VALUES** (only when period_type = 'duration'): - `quarterly` - ~3 months duration - `semi_annual` - ~6 months duration - `nine_months` - ~9 months duration - `annual` - ~12 months duration - `other` - Non-standard durations Note: Element.period_type indicates the expected period type for that metric - different from Period.period_type!

get-example-queries

Basic facts about shared repository `sec`: graph id, approximate node count, node labels, relationship types, whether it is read-only. **WHEN TO USE:** - To confirm which graph you are connected to and what it holds before `get-graph-schema` - To size a query from the node count and label list without reading the full schema **RETURNS:** A small JSON object. Takes no arguments.

get-graph-info

**GRAPH:** shared repository `sec` — public, read-only data. Get the graph schema: each node table with its property names, and each relationship table with its source and target node. **WHEN TO USE:** - Start here to understand the data structure - Before writing queries, to check property names and relationship directions - When exploring what data is available in the graph **RETURNS:** A list of tables, nodes first, then relationships: - **Node**: `label`, `properties` (names only; the core node types list their key properties), and a `description` / `comment` when one exists - **Relationship**: `label`, `from_node`, `to_node`, and a `description` / `comment` when one exists Property data types, keys and row counts are not included. **NOTES:** - Check relationship direction: ->() vs <-() - Property names are case-sensitive

get-graph-schema

One section of a report read whole — THE EXPENSIVE CALL (4–30K characters): rows in presentation order with depth and label; `values` = the consolidated fact per period column; `members` = the same row broken out by the block's own axes; `axes` with the members that carry facts; `calculation` = every total's children with weights and a footing check per period; `text` = the section's text blocks. Call `disclosures` first to find the block id, then call this once per block — not once per question. **WHEN TO USE:** - A derived question about one section: "which line items make up operating expenses", "how does long-term debt break down by instrument", "does the tax rate reconciliation foot" - Segment, maturity, roll-forward and reconciliation tables — the breakdowns a statement view hides - Never for a whole filing: one block per call **PARAMETERS:** - `block` (required) — the block `id` from `disclosures`; a role name or its last segment also resolves - `ticker` / `report_id` — as for `disclosures` - `periods` — period keys to keep, from a previous call's `columns`; the default keeps the budgeted set, year and balance columns first on an annual form - `member` — keep only breakdowns whose member key contains this text (a segment name) - `max_rows` (default 400) / `max_members` (up to 200) — explicit caps when you want less than the budget - `offset` — rows to skip: the `next_offset` a truncated response returned **RETURNS:** - `block` — id, role, name, disclosure, level; `siblings` (the rest of the family); `merged_roles` when a second drawer of the same section folded in - `columns` — the period keys shown; `rows` — depth, concept, label, `values` and/or `members`, `abstract` on headers; `members_omitted` / `periods_omitted` on a row a cut touched - `axes` (each with the members that carry facts and its default), `calculation` (`foots` / `checked` counts per total; `differences` only where |reported − computed| exceeds half a unit at the stated precision), `text` - `truncated` when `max_rows` cut the walk, with `next_offset` for the next page (a later page adds `ancestors` and leaves out axes, calculation and text); `resolved_report` when a ticker was resolved, with `links` on SEC (`viewer` opens the filing in the xbrlkit viewer — give the user that URL to show it) **NOTES:** - Budgeted, not counted: breakdowns and columns are kept most-reported / most-recent first up to about 16K characters of cells each; a small table is never cut, and a row is never left blank by a cut - A footing difference is usually the filer's own tagging (an element swap, a fact in the wrong context) — read the section's text before calling it an error - On the SEC repository the report is the published filing; a filing processed before its artifacts existed answers "not published yet" until the repository is reprocessed. A `text` entry marked `external` is a text block whose fragment could not be read; read it with `search-documents` and `get-document-section` **RELATED TOOLS:** - `disclosures` — the map; call it first - `financial-statement-analysis` — the primary statements as flat rows, cheaper when no breakdown is needed - `build-fact-grid` — a slice of facts across reports and entities - `get-information-block` (tenant graphs) — one authored block's envelope with its rules and verification; this is the section read whole from the ledger's report

information-block

List every subgraph under this parent graph, plus the parent itself as the `primary` entry. **WHEN TO USE:** - To discover what subgraphs exist and how to reach each one - Before working in a subgraph, to get its `connector_url` **RETURNS:** One row per graph — the parent as `primary` plus each subgraph — each carrying `connector_url`, the MCP endpoint that serves that graph. **NOTES:** Each subgraph is served at its own endpoint, its `connector_url`. This connection stays on its own graph and cannot be retargeted, so the tools here answer only for this graph; a subgraph is reached by the user connecting its URL. **Credential:** the result's `credential` field says how this connection authenticates. A key scoped to a parent graph also covers its subgraphs. An OAuth grant covers exactly one URL. From a subgraph, the parent or a sibling needs its own authorization or a key from the app's MCP page (/connect).

list-subgraphs