build-fact-grid
ChatGPTConstruct 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.
describe-filing
ChatGPTHow 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
disclosures
ChatGPTThe 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
financial-statement-analysis
ChatGPTReturn 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)
get-document-section
ChatGPTRead 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-example-queries
ChatGPTGet 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-graph-info
ChatGPTBasic 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-schema
ChatGPTGRAPH: 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
information-block
ChatGPTOne 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
list-subgraphs
ChatGPTList 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).
read-graph-cypher
ChatGPTGRAPH: 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. - Text is not a Cypher question here: string matching (CONTAINS, STARTS WITH, ENDS WITH, =~) on Fact.value or Fact.uri is refused. search-documents searches filing text; search-text searches inside one filing; disclosures then information-block reads one section whole. - get-example-queries` carries these as working patterns; run it first.
read-text
ChatGPTRead one filing's whole text from a character offset — a search-text hit's offset, or a section's from describe-filing. Returns next_offset while more follows; call again with it to read on rather than answering from a partial read. WHEN TO USE: - After search-text, to read the passage around a hit before quoting it - To read a whole Item from the offset describe-filing gives PARAMETERS: - offset (default 0), length (default 4000, max 8000) - ticker / report_id / fiscal_year / period_type / accession / form — the same filing search-text read RETURNS: - text, offset, length, text_chars (the whole text), next_offset, and the section the window starts in - resolved_report.links on SEC — viewer, as_filed, edgar, as for search-text
resolve-element
ChatGPTResolve 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.
search-documents
ChatGPTSearch 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 - snippet_chars — approximate snippet budget per hit (default 400, max 1500); raise it when the snippets are too short to choose between hits RELATED TOOLS: - get-document-section / get-document — read what a hit points at - search-text — once you know the filing, search INSIDE its whole text (cover page, footnotes, anything between the indexed sections); pass a hit's accession_number as accession with its entity_ticker (a CIK for a filer with no ticker) - read-graph-cypher — structured data (numbers, relationships), not prose - list-documents — browses by metadata; does not search content - resolve-element — takes a qname from get-document-section's xbrl_elements on to its structured values RETURNS: - Ranked hits, each with document_id, score, source_type, section_label, section_id, snippet, content_length and content_url (element_qname for an iXBRL disclosure) - Filing fields every hit shares (entity_ticker, entity_name, form_type, filing_date, fiscal_year, accession_number) appear once at the result root; when the hits span filings they stay on each hit - The same section from a filer's successive filings comes back once, as its best-ranked (then newest) filing; also_in_filings counts the other filings folded into it. With entity set nothing is folded, so pass a ticker or CIK to see one filer's filings of a section side by side - total counts matching documents before any folding (OpenSearch stops counting at 10,000), not the distinct results a page can show - A snippet is an excerpt around the match, not the passage — read the section with get-document-section before quoting a figure from it - A long section (an MD&A, a commitments note) is indexed in parts of about 25K characters; a hit carries part / part_count and the parts share a parent_document_id. get-document-section returns one part and its next_document_id - For user docs, use get-document to retrieve the complete document NOTES: - Searches user-uploaded documents (created via create-document), SEC filing text blocks and narrative sections, and iXBRL disclosure sections - To tie narrative back to reported numbers: get-document-section returns an iXBRL disclosure's xbrl_elements (e.g. us-gaap:Goodwill); look one up with resolve-element, then read-graph-cypher for its structured values. 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. Only a CIK selects exactly one filer. A company name is a loose word match that takes in other filers sharing a word ("Acme Holdings" also matches every filer with "Holdings" in its name), and so is a ticker that is also a word ("ON" also matches filers with "On" in their names) — pass the CIK when it matters - Use section filter (item_1a, item_7) to target specific filing sections, or an element qname (us-gaap:CommitmentsAndContingenciesDisclosureTextBlock) to target one iXBRL disclosure across filings; the element filter finds the disclosures that contain a given fact
search-text
ChatGPTSearch INSIDE one filing: every place its whole text says something, in document order, with the surrounding text. On SEC the text is the filing's own document — a 10-K, 10-Q, 20-F or 40-F from any processed year, or an 8-K earnings release with its exhibits — so it finds what no indexed section carries: the cover page, a footnote to a table, an exhibit, a passage between Items. WHEN TO USE: - A question about one filing that its indexed sections or its facts do not answer: "does the 10-K mention a going concern", "what guidance did the earnings release give" - To find every mention of a term in one filing, not the best-ranked few - search-documents finds WHICH filings discuss something, across the corpus, ranked; search-text finds WHERE in one filing, exhaustively. Find the filing first, then search inside it PARAMETERS: - query (required) — whole words matched in order across any spacing, case-insensitive: customer concentration; a word also finds its -s / -es plural and possessive (tariff finds tariffs); any other ending needs a stem (compan* for companies). Split phrases with | to match any of them; end a word with * for a stem (terminat*); a * on its own is ignored. Not a regular expression - ticker (+ fiscal_year / period_type, or form: "8-K", or accession), or report_id — as for describe-filing - window — characters of context around each match (default 300, max 1500); max_hits (default 10, max 25) RETURNS: - total matches; hits — offset, match, text around it, and the section it falls in - sections — where all matches fall when there are more than the hits shown - terms — on no match, how often each of your words occurs alone: search again with the wording the filing uses - text — "primary document", or "tagged text blocks" for a filing without its document - resolved_report.links on SEC — viewer opens the filing in the xbrlkit viewer (give the user that URL to show it), as_filed, an 8-K's exhibits, edgar NOTES: - Pass a hit's offset to read-text to read on from it before quoting