RoboSystems

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` …

Delete a semantic memory by its id. **WHEN TO USE:** - To remove an outdated or incorrect memory - To correct one instead, prefer `update-memory`, which keeps the id and its history **PARAMETERS:** - memory_id: from a prior `remember` or `recall` **RETURNS:** Confirmation of the deletion.

Fetch a single counterparty (agent) by id. **WHEN TO USE:** - To look up a customer, vendor, or employee record - To check an agent's contact info and source linkage before creating an event - To verify whether a counterparty exists before assigning agent_id on an event **PARAMETERS:** - id (required): Agent id (agt_ prefixed ULID) **RETURNS:** An AgentResponse with id, agent_type, name, legal_name, contact fields, source/external_id provenance, and is_active status. **RELATED TOOLS:** - list-agents — browse agents with filters - agent-activity — events and transactions for an agent - crea…

Get the canonical month-end close playbook — the tool sequence, the setup decisions, and the gotchas that no single tool's schema makes obvious. **Call this FIRST when setting up or running a close** (or whenever you're unsure what to call next). Guidance only — no data, no side effects, safe on read-only graphs. Version-locked to this build, so it never drifts from the actual tools. **WHEN TO USE:** - Before authoring recurring schedules (depreciation/amortization/prepaid) for the first time → mode="initiate" - Before running a monthly close → mode="recurring" - Any time the close workflow i…

Description is built at runtime.

Fetch a single Event Block envelope by id. **WHEN TO USE:** - To inspect an existing business event (invoice, contract, bank transaction, …) - To check an event's current status and audit chain - Before updating or voiding an event **PARAMETERS:** - id (required): The event id (evt_ prefixed ULID) **RETURNS:** An EventBlockEnvelope with: - event_type, event_category, status - REA primitives: agent_id, resource_type - Occurrence: occurred_at, effective_at, and due_date on an invoice or bill - Provenance: source, external_id - Economic value: amount, currency - metadata (event-type-specific p…

Fetch a single event handler rule by id. **WHEN TO USE:** - To inspect what a specific handler does before modifying it - To verify whether a handler is active or approved - To check the transaction_template DSL for a handler **PARAMETERS:** - id (required): EventHandler id (hdl_ prefixed ULID) **RETURNS:** EventHandlerResponse with match criteria, transaction_template, priority, is_active, origin, and AI provenance fields. **RELATED TOOLS:** - list-event-handlers — browse handlers with filters - preview-event-block — dry-run to see which handler fires for an event - create-event-handler —…

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 …

Get the current fiscal calendar state — what period is next to close, what's blocking it. **NEW TO THE CLOSE? Call `get-close-playbook` first** — it lays out the full tool sequence, the schedule-setup decisions, and the gotchas this tool's output assumes you know. **WHEN TO USE:** - At the START of every close session — check what period you're working on - Before calling close-period — verify it will succeed (check `closeable_now`) - To check catch-up state when a user is behind ("close the books — I'm 3 months behind") **PARAMETERS:** - entity_id (optional): the entity whose calendar to r…

Description is built at runtime.

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` …

Check data freshness on BOTH sync edges: source system → OLTP (per-connection health + last sync outcome) and OLTP → LadybugDB graph (staleness / materialization). **WHEN TO USE:** - Before querying financial data, to verify the graph is current - After OLTP writes, to check if rematerialization is needed - After sync-connection, to verify the sync finished and see what it did (captured / updated / reconciling_items / dispatch_failed counts) - When the user asks about data freshness or a connection's health **RETURNS:** sync_status (`fresh`/`stale`), stale_since, stale_reason, stale_duration…

Return the GraphQL schema for the extensions endpoint. **WHEN TO USE:** - Before query-graphql, to discover types, fields and input arguments - When a query fails on an unknown field — the schema is per-deployment and depends on which extensions (roboledger, roboinvestor) are enabled **PARAMETERS:** - ``format``: ``sdl`` (default) is human-readable Schema Definition Language, best for scanning types and writing queries; ``introspection`` is the full JSON introspection result, for tooling that consumes the standard format. **RETURNS:** The schema in the requested format.

Fetch a single Information Block envelope by id. **WHEN TO USE:** - To inspect an existing block (schedule, statement, disclosure, …) — full detail - To see the block's atoms (elements, connections, facts) and typed mechanics - Before drafting work that depends on the block's current state **PARAMETERS:** - id (required): The Information Block's structure id - scenario_id (optional): A forecast block's structure id — binds that scenario's FactSet slice instead of actuals (statement envelopes show the latest computed forecast month; metric envelopes extend the series with the scenario's…

Get coverage statistics for account rollups (CoA → GAAP mapping). **WHEN TO USE:** - To check progress during a mapping session - To verify account rollups are complete before closing the books - To see how many accounts are mapped vs unmapped - To review confidence distribution of AI-suggested mappings **RETURNS:** - Total CoA elements, mapped count, unmapped count, coverage percentage - Confidence distribution: high (>0.90), medium (0.70-0.90), low (<0.70)

Get an overview of what schedule-derived work has been done for a fiscal period. **WHEN TO USE:** - At the start of a close session to see what's pending - After creating entries to verify progress - To generate a close summary for the user - To read the receipt after close-period — including when it handed back `status: "in_progress"` and the close is still finishing on the worker **PARAMETERS:** - period_start / period_end (required): The fiscal period dates - entity_id (optional): the entity whose schedules to read; omit for the group parent **RETURNS:** - Period status (open/closed)…

Get a short-lived download link for a published report, as a file another tool can open. **WHEN TO USE:** - To open a report in a local XBRL reader or report viewer that loads a file by URL - To hand a report to a tool outside this graph as a standards-form document **PARAMETERS:** - `report_id`: the report. List them with query-graphql: `{ reports { reports { id name generationStatus } } }` - `format`: `holon-jsonld` (default) is the JSON-LD holon, the one format that carries the whole report; `holon-jsonld-lineage` the same holon with its `#lineage` graph — the ledger lines, entries and ev…

List Chart of Accounts elements that are not yet mapped to US GAAP reporting concepts. **WHEN TO USE:** - At the start of a CoA → GAAP mapping workflow - To check which accounts still need mapping - To track progress during an iterative mapping session **RETURNS:** - List of unmapped CoA elements with id, code, name, classification, balance_type - EFS trait (asset/liability/equity/revenue/expense) helps narrow the target reporting concept - On a group, one entity's chart: `entity_id` names it (or `mapping_id` does, through the entity whose chart it maps); default the group parent's - liquidi…

Set up an entity's fiscal calendar — the one-time step before its first close. **WHEN TO USE:** - get-fiscal-calendar returns `calendar_not_initialized` for the entity - A new subsidiary (create-entity) is about to keep books: after its chart (initialize-chart-of-accounts), before recording its opening balance **THE DECISION — pass exactly one (ask the user if it is not clear):** - `first_open_period`: the first month THESE books will close. Every month from it through the current month is created open, and the first close is that month. Use for new books, and for books cut over from a…

List counterparty agents with optional filters. **WHEN TO USE:** - To find all customers or vendors - To search for agents from a specific source (quickbooks, xero, plaid) - To list inactive agents when reviewing counterparty records **PARAMETERS:** - agent_type (optional): 'customer' | 'vendor' | 'employee' | 'owner' | 'supplier' | 'government' | 'lender' | 'self' | 'other' - source (optional): 'quickbooks' | 'xero' | 'plaid' | 'native' - is_active (optional, default true): pass false to include inactive agents - limit (optional, default 50, max 1000) - offset (optional, default 0) **RETUR…

The graph's management dimensions — departments, classes, locations, projects — and their members, the tags a ledger line can carry. **WHEN TO USE:** - "What departments do we have?", "show the P&L by location": find the axis and its members first - Before tagging a journal line (`dimension_ids` on a line of a `journal_entry_recorded` event, or `line_dimensions` on `update-journal-entry`): a line takes a member's id, one per axis - Before `create-dimension`, to check the member is not there already **PARAMETERS:** - dimension_type (optional): one axis, e.g. `department`; omit for all - inclu…

List Event Block envelopes with optional filters. **WHEN TO USE:** - To find events of a specific type (e.g., all invoice_issued events) - To review events by status (e.g., all captured events awaiting classification) - To see a counterparty's event history (filter by agent_id) - To audit events from a specific source (quickbooks, plaid, etc.) - Close workflow: find unposted bank and source lines (status=captured or classified). Committed events are already posted or are evidence, not work - Post-sync reconciliation: is_reconciling_item=true lists reconciling items — committed events whos…

List event handler rules with optional filters. **WHEN TO USE:** - To see all handlers for a specific event type (e.g., 'invoice_issued') - To find handlers awaiting approval (approved=false) - To audit the active rule set before adding a new handler - To check which event types currently have an active handler set **PARAMETERS:** - event_type (optional): Filter by event type (e.g., 'invoice_issued', 'bank_transaction') - is_active (optional, default true): Include inactive handlers by passing false - origin (optional): 'hub' | 'tenant' - approved (optional): true = only approved; false = on…

List Information Block envelopes, optionally filtered. **WHEN TO USE:** - To discover what blocks exist for a graph - To filter by block_type (e.g., all schedules, all statements) - To browse by category (e.g., all Close-category blocks) **PARAMETERS:** - block_type (optional): Filter by block type id (e.g., 'schedule') - category (optional): Filter by registry category (e.g., 'Close') - limit (optional, default 50): Max results to return (1-1000) - offset (optional, default 0): Pagination offset - scenario_id (optional): A forecast block's structure id — each envelope binds that scenario'…

List the `coa_mapping` Structures on the tenant graph. **WHEN TO USE:** - At the start of any mapping workflow, to discover the active mapping structure id without dropping out of the typed MCP surface - Before calling `get-mapping-summary`, `get-unmapped-elements`, or `create-mapping-association` — each of those takes a `mapping_id` that you get from here **RETURNS:** List of mapping structures with id, name, block_type, taxonomy_id and framework — the reporting framework each maps the chart into. A chart holds one mapping per framework; the book mapping (`rs-gaap`) is listed first. O…

List all draft closing entries in a fiscal period with full line item detail. **WHEN TO USE:** - After drafting closing entries, BEFORE calling close-period - When the user asks "what's pending" or "show me the drafts" - To review exactly what will be committed on close **WORKFLOW:** 1. Draft entries come into being two ways — there is no `create-closing-entry` tool: - **Schedule-derived** (depreciation, amortization, prepaid roll-off): call `promote-obligations` to draft every matured schedule entry for the period in one sweep (the on-demand form of the background promoter),…

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 u…

Generate a live financial statement directly from the current tenant's OLTP ledger data using the active CoA→GAAP mapping. **WHEN TO USE:** - When the user asks for *their* books — "show me my income statement", "my balance sheet for Q1" - Live, up-to-the-minute data (no materialization required) - Only available on RoboLedger tenant entity graphs (not SEC shared repo) **PARAMETERS:** - `entity_id` (optional) — the entity whose books to render; omit for the group parent - `scope` (optional, default `entity`) — `entity` is one entity's own books. On the group parent, `combined` sums every mem…

Rebuild LadybugDB for this graph from its source data — either staged DuckDB tables (for file uploads) or the extensions OLTP database (roboledger / roboinvestor writes). **WHEN TO USE:** - After significant OLTP writes, to refresh the queryable graph - After uploading and staging new files - When `get-graph-sync-status` reports `stale` - When the user asks to rebuild or refresh the graph **PARAMETERS:** - source: `extensions` (OLTP) or `staged` (DuckDB). Auto-detected from graph_type if omitted. - dry_run: Validate without writing (returns a preview synchronously). - rebuild: Drop existin…

The consolidating entries a group's month needs, computed from the books. Posts nothing. **WHEN TO USE:** - "What consolidating entries does August need", "are the eliminations up to date", "why does the consolidated balance sheet still show the investment" - Before posting a consolidating entry by hand: see what the engine would post, and whether a hand entry of the same kind already covers it - After a member's month changes: what moved in the eliminations and the noncontrolling interest **PARAMETERS:** - `period` (required) — the month, YYYY-MM **RETURNS:** - `proposals` — one entry per …

Execute a read-only GraphQL query against the extensions endpoint. **WHEN TO USE:** - For typed reads of extensions data (roboledger, roboinvestor) - After get-graphql-schema, which gives the types and fields to query against **PARAMETERS:** - ``query``: the GraphQL query string. Mutations and subscriptions are rejected. - **graph_id is set from context** — never pass it as a query argument. The schema already reflects the graph_id from the URL. **RETURNS:** The query result, shaped by the fields requested. **NOTES:** A minimal query looks like ``{ fiscalCalendar { closedThrough closeTarge…

Description is built at runtime.

Recall stored semantic memories for the active graph by meaning rather than keywords. **WHEN TO USE:** - Before answering, to retrieve remembered context - When the user refers to something established in an earlier session **RETURNS:** The top-k most relevant memories with their ids and similarity scores.

Store a durable semantic memory for the active graph. **WHEN TO USE:** - For facts, decisions, preferences and context worth persisting across sessions - When something learned in this session should survive it **RETURNS:** The stored memory's id, for later `update-memory` or `forget`. **RELATED TOOLS:** - `recall` retrieves what this stores - write-graph-cypher builds structural graph data on subgraphs; this is vector memory and does not put anything in the graph

Reopen a closed fiscal period so adjustments can be made. **WHEN TO USE:** - A missed entry was discovered after a period was closed - A correcting entry is needed for a prior period adjustment - The user wants to re-run the close workflow for a closed period **NOTES:** 1. Transitions FiscalPeriod from 'closed' → 'closing' (drafts may still exist) 2. Only the latest closed period (closed_through) can be reopened; closed_through retreats one month 3. Retracts the month's canonical statement FactSets (a reopened month is no longer a closed assertion; re-closing restamps them fresh) 4. Do…

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,…

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 t…

Set whether a connection writes back to its source system — the explicit opt-in for outbound write-back. **NOTES:** - `qb_authoritative` (the default): QuickBooks is the book of record. RoboSystems-originated entries publish to QuickBooks when executed (`execute-event-block`) or at period close, then post locally. - `shadow`: QuickBooks is the book of record and nothing is written to it; the close posts nothing locally either, its drafts become shadowed expectations and its gates are findings. - `native` is not a choice here: it is what disconnecting or severing leaves, books kept in RoboSyst…

Find matching rs-gaap reporting concepts for a CoA element. **WHEN TO USE:** - When deciding which reporting concept a CoA account should map to - Narrows by classification (asset→Assets subtree, revenue→Revenues subtree, etc.) **RETURNS:** Candidate rs-gaap concepts with element id, qname, label and depth. Every candidate appears in at least one rs-gaap-presentation Network, so any target picked from here is guaranteed to render on the standard BS / IS / CF / SE reports under the active Reporting Style. **NOTES:** - Candidates are filtered by the EFS trait (FASB elementsOfFinancialStatem…

Pull fresh data from this graph's connected source system (e.g. QuickBooks) into the ledger. Async — dispatches the provider's sync pipeline and returns immediately. **WHEN TO USE:** - Before a period close when `get-fiscal-calendar` reports the `sync_stale` blocker (source sync older than period end) — sync first instead of passing `allow_stale_sync=true` - When the user says the source system has new transactions - After a code-level chart-of-accounts / mapping change that must back-propagate: set `full_rebuild=true` **PARAMETERS:** - connection_id: Omit to auto-resolve the graph's single …

Update a stored semantic memory in place by its id. **WHEN TO USE:** - To correct or refine a memory — prefer this over forget plus remember, which mints a new id and drops the memory's history **PARAMETERS:** - memory_id: from a prior `remember` or `recall` - Only the fields supplied change; the memory is re-embedded when `text` changes **RETURNS:** The updated memory.

Execute a write Cypher query on the active subgraph. **WHEN TO USE:** - To create, update or delete data in a subgraph - Only on subgraphs — the parent graph is not writable here **PARAMETERS:** - ``query``: Cypher limited to CREATE, MERGE, SET, DELETE, REMOVE **RETURNS:** `success`, plus `result` — the rows the query itself RETURNs, which is empty for a bare CREATE or SET. There is no affected-row count; to confirm a write, RETURN what you wrote. **Examples:** ```cypher // Create a node CREATE (c:Concept {identifier: 'c1', name: 'revenue', category: 'metric'}) // Create a relationship MA…