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 **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. 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

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) - `ticker` / `report_id` — which one is required depends on the graph; see NOTES **RETURNS:** - Deduplicated facts (qname, name, value, end_date) ordered by end_date DESC - resolved_report info when auto-resolution was used - Dimensional/segment breakdowns are filtered out (consolidated totals only)

financial-statement-analysis

Retrieve the full text of a document section by ID. Use this after search-documents to read the complete narrative content of a relevant result. **WHEN TO USE:** - After search-documents returns results, use the document_id from a hit to get the full section - When you need the complete text of an MD&A, risk factor, or business description - To read the full context around a search snippet **RETURNS:** - The section text with 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 on; 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 list of 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, and 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 complete database schema showing all node types, properties, and relationships. **WHEN TO USE:** - Always start with this tool to understand the data structure - Before writing queries to verify property names and relationships - When exploring what data is available in the graph - To understand custom schema definitions **RETURNS:** Comprehensive schema information including: - **Node Types**: Label, properties with data types, primary keys - **Relationships**: Label, properties, source/target nodes - **Property Details**: Name, data type (STRING, INT64, DOUBLE, etc.), nullable flags - **Metadata**: Descriptions and additional context when available **NOTES:** - Look for node labels ending in specific patterns (Entity, Fact, etc.) - Check relationship direction: ->() vs <-() - Property names are case-sensitive - Use count properties to understand data volume

get-graph-schema

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:** A subgraph is a separate endpoint, not a mode of this one: this connector is anchored to its own graph by URL and cannot be retargeted. To work in a subgraph, add its `connector_url` as its own MCP connector. **Credential:** depends on how this connector authenticates — the result's `credential` field says which. A key scoped to a parent graph also covers that parent's subgraphs, so a key-based connector on the parent reuses its own key on any subgraph listed here. An OAuth grant is bound to exactly one URL, so an OAuth connector authorizes the subgraph URL when adding it (consent shows it locked in). Going the other way — from a subgraph to its parent or a sibling — neither reaches: authorize the target URL, or generate a key for it from the app's MCP page (/connect).

list-subgraphs

**GRAPH:** shared repository `sec` — public, read-only data. Execute read-only Cypher queries against the graph database. **WHEN TO USE:** - To traverse the graph directly when no typed tool covers the question - Call `get-graph-schema` first to discover node types and relationships **RETURNS:** The rows the query RETURNs, as records. Read-only: the write verbs are rejected before execution, and query complexity is monitored. **NOTES:** - Always include LIMIT clause for large result sets - Use WHERE clauses to filter data effectively - Check for NULL values: WHERE n.property IS NOT NULL - Use CONTAINS for text search: WHERE n.name CONTAINS 'keyword' - When joining multiple relationships from the same node, use comma-separated patterns in a SINGLE MATCH clause: `MATCH (n)-[:R1]->(a), (n)-[:R2]->(b)` (not separate MATCH clauses) **WORKFLOW:** ```cypher // Count nodes by type MATCH (n) WITH labels(n) AS label, count(n) AS count RETURN label, count ORDER BY count DESC // Explore node properties MATCH (n:Entity) RETURN keys(n) LIMIT 1 // Find relationships between node types MATCH (a)-[r]->(b) RETURN DISTINCT labels(a)[0] AS from_type, type(r) AS rel_type, labels(b)[0] AS to_type ``` **RELATED TOOLS:** `get-graph-schema` for what is in the graph, and `get-example-queries` for patterns that already work against it. **SEC DATA RULES — a query that ignores these returns a plausible wrong number:** - Consolidated vs dimensional: `Fact {has_dimensions: false}` is the consolidated total; `true` is a segment / geography / member breakdown. Mixing them double-counts. - Canonical concepts over qnames: filter `Element.canonical_concept` ('revenue', 'net_income', 'total_assets', ...) rather than one qname — filers tag the same concept differently (us-gaap:Revenues vs us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax). `resolve-element` maps a concept to its qnames. - Period shape: income-statement and cash-flow facts are durations — pin `Period {duration_type: 'annual'}` (or 'quarterly'); balance-sheet facts are `Period {period_type: 'instant'}`. Quarterly, year-to-date and annual figures share end dates, so an unpinned period mixes them. - Anchor on the Entity (`{ticker: ...}` or CIK) or a Report first and reach `Structure`, `Element` or `Period` last — ~53k filings share a `Structure.canonical_type`, and leading with it scans them all. Always `LIMIT`. - `RETURN DISTINCT`: a fact is restated in later filings and sits in more than one FactSet, so an un-deduplicated result repeats rows. - `get-example-queries` carries these as working patterns; run it first.

read-graph-cypher

Resolve a financial concept (like "revenue" or "total assets") to the actual XBRL element names used in the graph. **WHEN TO USE:** - BEFORE writing Cypher queries that filter by element qname - When you know the business concept but not the XBRL tag name - To discover which companies report a given metric and how **RETURNS:** - Canonical concept match (if found in taxonomy) - Top matching XBRL elements with qnames, labels, and fact counts - A ready-to-use Cypher query hint **NOTES:** - concept: "revenue" → finds us-gaap:Revenues, us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax, etc. - concept: "total debt" → finds us-gaap:LongTermDebt, us-gaap:DebtAndCapitalLeaseObligations, etc. Use the returned query_hint directly in read-graph-cypher for immediate results.

resolve-element

Search across documents. Keyword (BM25) by default; set `semantic=true` to add KNN. Covers SEC filing narratives, user-uploaded documents (policies, procedures, notes), and any other indexed content. **WHEN TO USE:** - To find accounting policies, close procedures, or reference documents - To search SEC filing narratives (MD&A, risk factors, disclosures) - To discover any document content by topic or keyword - For cross-company topic search on shared repositories (e.g., "which companies mention tariff risk?") **PARAMETERS:** - `query` (required) — the search text - `semantic` — adds KNN to the BM25 pass; defaults to false, so a plain call is keyword-only - `entity`, `form_type`, `section`, `element`, `fiscal_year`, `size` — filters **RELATED TOOLS:** - read-graph-cypher — structured data (numbers, relationships), not prose - list-documents — browses by metadata; does not search content - get-document-section / get-document — retrieve what a hit points at **RETURNS:** - Ranked results with relevance scores and text snippets - Each result includes a document_id — use get-document-section for the full section text - For user docs, use get-document to retrieve the complete document - iXBRL results include xbrl_elements for graph cross-reference **NOTES:** - Searches user-uploaded documents (created via create-document), SEC filing text blocks and narrative sections, and iXBRL disclosure sections - iXBRL results carry xbrl_elements (e.g. us-gaap:Goodwill). Look one up with resolve-element, then read-graph-cypher for its structured values — this is the bridge from narrative context to financial facts. Note resolve-element is only published on graphs with semantic enrichment - Natural language queries work well ("depreciation policy", "month end close procedures") - Use entity filter to focus on one company's filings - Use section filter (item_1a, item_7) to target specific filing sections

search-documents