PipeLedger Tool Guide

Does

Start every session with identity. Establishes who the agent is connected as, what it may access, and whether its answers represent the whole organization or a limited slice. Provides guidance to carry into every answer.

Returns

Organization, credential label, role, exact allowed tools, effective operator grants, clearance, dimension scope, row filters, allowed datasets, and ledger.complete with reasons. Includes guidance: a plain-language explanation of the credential’s access to carry into answers.

Scope

Which data this credential may access: the whole organization, selected Legal Entities, or rows limited by business, geographic, or functional segment, project, or other row filters. Clearance and identity policy separately determine which account amounts, detail, and original identities may be returned.

Example prompt

What can I access in this session, which tables can I query, and which tools can I use?

Important details

Inputs. Takes no arguments.

Interpreting totals. Read scope together with ledger.complete and its reasons. A complete ledger for selected Legal Entities is not the whole organization. Never present a partial slice as company-wide. A tool missing from allowed_tools is not granted to this connection; that does not mean the capability does not exist.

Security. Never returns the bearer token or key material. PipeLedger’s agent tools cannot add users or grant tool, read, or write permissions. Access is controlled by human Owners and Admins through PipeLedger’s administration interface.

Identity before data. Know whether the answer covers the whole ledger or an authorized slice.

Does

Shows aggregate and request-level PipeLedger usage for work performed through this connection.

Returns

Exact totals for the selected requests, session, or time window, including Financial Intelligence Query (FIQ) units and warehouse billed bytes. Request details include tool names, timestamps, outcomes, and billing-record delivery state. The response indicates when request detail is truncated; aggregate totals still cover the full selection.

Scope

Access is limited to the calling credential within its organization. It does not combine usage from a user’s other credentials.

Filters

Uses the current host session when the host supplies session metadata. Exact request_ids select specific requests; evaluation_scope=agent with a bounded time window covers this credential’s sessions.

Example prompt

How much PipeLedger usage did the quarterly board reporting package incur?

Important details

Workflow context. Measure a reporting package using its session or request IDs; the tool does not identify a package by name. Usage records contain metering evidence, not prompts, SQL, or financial results.

Metering. The totals cover PipeLedger usage, not the AI host’s token bill. The lookup is itself metered; its own event can appear in a later lookup.

Self-scoped usage evidence: what was metered, and why.

Does

Maps financial language and business names to matching metrics, reports, Legal Entities, and business objects. Recognizes aliases, source identifiers, approved consolidated reporting objects, and permitted corporate-family names to help the agent select the right data.

Actions

search finds ranked matches for a name, identifier, or financial term. list browses governed reporting objects. review pages underlying source records and evidence. context reads published company profiles, groups, and direct ownership for a specified date or period.

Returns

Search candidates, source evidence, or dated entity profiles, relationships and change events, depending on the action. Includes publication references. The agent should clarify ambiguous matches before querying.

Scope

Only objects permitted by the credential’s access and identity policy. Tokenization preserves directory objects under private labels. Entity Context additionally requires Highly Restricted clearance, permitted original identities, and explicit Entity Context and Business Object Directory column access.

Resources

metric, customer, vendor, employee, project, and legal_entity. Each call selects one object_type.

Example prompt

Which Harborline supplier record should I use, and which company in our group is it associated with?

Important details

Action coverage. Search supports all six object types. List supports customers, vendors, employees, projects, and Legal Entities; use pl_catalog to list metrics. Review currently supports customers, vendors, and employees.

Entity context. Use action=context, object_type=legal_entity, and exactly one context.as_of date or context.period. Reuse exact entity IDs from the directory and follow pagination. Dates describe when recorded facts apply; publication references identify when those facts became available. Saved settings reach this lookup only after publication.

Interpreting context. Empty results or null fields do not prove that information is unrecorded: it may be unavailable or withheld. Ownership completeness is not asserted. Dated shares do not establish voting control, consolidation, or tax treatment. Returned party references can support a separate permitted pl_query.

Search coverage. This is not a search engine for transaction memos, item names, or purchase-order numbers.

Resolve the business object before interpreting the numbers attached to it.

Does

Explains what one row represents in a permitted published dataset, what its columns mean, and how the data can be filtered or grouped.

Actions

Read concise structure, including dataset grain and column grouping flags, by default. Use detail=full for complete column descriptions.

Returns

The dataset’s grain, policy-visible column names and types, per-column filterable and groupable flags, and column_group headings. Also returns masking markers, aggregation support, recommended query metrics, supported time buckets, fiscal-calendar context, and the same credential description as pl_whoami.

Scope

One published dataset that the credential may access, with columns limited by its delivery policy.

Filters

Use columns to narrow the response to named fields.

Example prompt

Project Overview shows four revenue columns. What does each one mean, and when should I use it?

Important details

Reading the schema. grain describes what one row represents. groupable identifies columns available for query grouping; column_group organizes related columns under presentation headings. A presentation heading is not a query grouping.

Access and limits. The schema reflects the selected dataset and delivery policy. A visible column is not a promise that every combination of filters, scope, metric grain, and grouping is permitted. Temporal ratios belong in pl_report, not a single-dataset query.

Discover permitted columns and financial context before constructing a query.

Does

Reads the Finance Catalog: governed metric definitions used by queries and reports, saved reports, and the organization’s finance assumptions.

Actions

list, get, history, preview, versions, compare, governance, and assumptions.

Returns

Inspect canonical and organization-authored definitions, lifecycle status, definition hashes, revision history, and supported catalog releases. Preview an unsaved definition without creating or activating it.

Resources

Governed metric definitions, saved reports, catalog versions, governance information, and controller-supplied finance assumptions.

Example prompt

How is gross profit defined here, and when did its definition last change?

Important details

Governance. The governance snapshot distinguishes the Finance Catalog version from account-classification revisions. It reports whether governance is current or pending; it does not certify source-system freshness.

Assumptions. Read controller-supplied numeric assumptions using an explicit as_of date. These inputs have their own revisions and provenance; they are not calculated warehouse results.

Shared definitions, with versions and evidence that an agent can inspect.

Does

Maintains the definitions and business context behind financial reporting: metric definitions, account classifications, business identities, and dated legal entity settings.

Actions

Select resource and its supported action. Calls include create, edit, activate, and archive for metrics; list, create, edit, delete, and apply_templates for cash flow rules; history and annotate for account-semantics revisions; and list, review, and commit for entity_context.

Returns

The resource-specific result and operation status, with revision or review evidence where the selected action provides it.

Scope

Requires an Operator credential with this tool enabled and the permission for the selected operation.

Resources

Metric definitions, account and cash-flow classifications, presentation rules, transaction classification overrides, account-semantics annotations, finance assumptions, business-identity governance, and Entity Settings.

Example prompt

Draft a metric for shipping and delivery costs, then propose how to include those costs in gross profit without double-counting. Leave the draft and proposed treatment for our controller to review.

Important details

Security. Catalog authoring, metric activation, business identity governance, and Entity Context management have separate grants. An identity-link grant does not authorize company ownership or lifecycle changes. Only human Owners and Admins grant these permissions.

Metrics. Editing an active organization metric creates a draft revision; the current definition remains live until activation. Standard metrics such as Gross Profit are protected. Organization-specific formulas use distinct metric IDs.

Classification. Use edit for account classifications; list_candidates, edit, or void for transaction overrides. Rules and overrides change configuration immediately, without metric activation. These writes require Highly Restricted clearance, unrestricted scope, and no row filters.

Assumptions. create, edit, update_value, and submit prepare exact revisions for review. Only an Owner or Admin in the Finance Assumptions UI can approve, decline, or archive them, regardless of metric activation permission.

Identities. review prepares an exact identity-link or role change; commit applies it with its short-lived review token. Requires original-identity access, Highly Restricted clearance, unrestricted scope, no row filters, and an accountable Owner or Admin.

Entity Settings. For resource=entity_context, list current settings or history, review one exact change, then commit its token and fingerprint if you choose to proceed. Review saves a receipt; its proposed settings and events are simulated, not committed. Supports legal and tax profiles, reporting groups, direct ownership, and merger or dissolution events. For an ownership transfer, provide the seller, buyer, transferred share and date; review the calculated holdings before committing. Enter share_transferred as a fraction: 0.05 means 5% of the company, using the same units as ownership shares. Future ends on current holdings, later ownership periods or lifecycle records require resolution first. Requires its dedicated grant, Highly Restricted clearance, original-identity access, unrestricted organization scope without row filters, and an active accountable Owner or Admin.

Saving entity changes. Read current settings first and preserve unchanged values: a profile is complete desired state, so omitted optional values are cleared. Record the business-effective date and evidence; distinguish a real change from correcting a mistaken entry. Review validates the change but does not constitute human approval. Commit saves it; request publication separately through pl_run. Published reads use pl_resolve.

Access and limits. Never changes source ERP postings or authoritative debit and credit amounts. Transformation-dependent classification changes reach financial datasets through processing and publication.

Govern how financial information is interpreted while preserving the source books.

Does

Runs a parameterized query against a permitted published financial dataset. It does not accept free-form SQL.

Actions

Row mode returns records at the dataset’s native grain. Aggregation mode uses governed metrics and supported group_by columns to return one row per group.

Returns

Rows or grouped metric values, with source-publication and governance context and supporting drilldown handles when requested and available. A bounded result page is not evidence that the entire authorized population was returned.

Scope

Only permitted published datasets and rows within the credential’s Legal Entity, segment, project, and other access restrictions. Clearance and identity policy govern the detail returned. Preserve identity tokens exactly.

Resources

General Ledger Lines, Trial Balance, Cash Flow Components, Chart of Accounts, Project Overview, Project Financial Position, Unit Movements, and Unit Rollforward, subject to publication and access.

Filters

Use schema-advertised filters, sorting, limits, supported group_by columns, and semantic time buckets to select and organize the authorized data.

Example prompt

Show our five largest vendors by operating expense over the trailing twelve months, by business segment.

Important details

Metrics. Governed metrics supply their defined financial signs and calculation rules. Request drilldown handles for supporting detail where available.

Published rows or governed totals, with the scope and provenance needed to interpret them.

Does

Generates an Income Statement, Balance Sheet, Cash Flow Statement, or Metrics Report from approved published financial data.

Actions

report_type=income_statement, report_type=balance_sheet, report_type=cash_flow_statement, or report_type=metric_report for report execution. action=load_recipe for saved recipe instructions, without executing their financial steps.

Returns

Statement or metric values with financial controls, governed definition and publication context, and supporting drilldown handles where available. Loading a recipe returns its instructions and presentation notes instead of financial values.

Scope

Reports cover one selected Legal Entity or, when no entity is selected, all entities authorized for this credential. Reporting Legal Entity mappings bring source records for the same legal company together across connectors. Group reports use a consistent reporting currency and accounting-book basis.

Resources

Approved published financial data, governed metric definitions, active saved Metrics Reports, and saved report recipes.

Filters

Choose reporting_legal_entity_id for one authorized Legal Entity. Ordinary activity uses fiscal_year; balances use as_of; comparison_period supplies the appropriate comparison clock. Use exclude_intercompany to remove controller-tagged intercompany accounts from supported reports, including their comparison periods and drilldowns.

Example prompt

Show Riverside Lumber’s FY2026 Income Statement against FY2025.

Important details

Balance Sheet. Selects the Trial Balance for the calendar month containing as_of and reports that month’s closing position. It aggregates accounts within that snapshot, never balances across months. A comparison uses a separate comparison_period.as_of snapshot. For example, an April 17 input selects the April month-end position, not an April 17 daily balance.

Metrics Report. An explicitly selected, ordered packet of up to 50 governed metrics, or one active saved report. It can combine financial and unit metrics but accepts no request-time formulas or dimensional grouping. Temporal ratios use their definition-fixed window and an explicit eligible month-end.

Ledger queries. General Ledger and Trial Balance queries use pl_query.

Use the complete statement for statement questions; use Metrics Report for an explicitly chosen metric packet.

Does

Saves Metrics Reports and report recipes for reuse and sharing.

Actions

save creates a report; revise updates it; archive retires it. propose requests organization sharing; withdraw retracts your pending proposal.

Returns

Report definition and revision, or proposal status.

Scope

Personal reports belong to the accountable human; authorized Viewer credentials can save them. Organization writes require Operator authority plus the organization-report grant. Owners and Admins review proposals.

Resources

Metrics Report definitions: metric order, sections, and optional relative-period rules. Report recipes: reusable query and reporting instructions.

Example prompt

Save that Metrics Report as my monthly board packet and propose it for the finance team.

Important details

Saving. Metrics Reports use the signed save_handle from a successful pl_report run. Supplying recipe validates and saves instructions without executing them.

Reusing and sharing. Saved Metrics Reports store definitions, not results. Reruns use the current Finance Catalog and reader’s permissions. Proposals require approval before organization sharing.

Save the reporting workflow. Every run respects the reader’s current access.

Does

Opens the supporting detail behind a report line or an aggregate query result.

Actions

Pass the returned drilldown_handle unchanged and choose a supported target_grain to open its supporting detail.

Returns

Supporting rows or groups, provenance, staleness information, and reconciliation when the access basis, catalog, and publication still match. Changed evidence can make a comparison unavailable without proving a financial discrepancy.

Scope

The caller’s current access still applies to the underlying rows. Handles prove provenance, not permission; protected detail may be omitted.

Resources

Depending on the handle: account balances, period activity, transaction lines, or the dependencies of a derived metric. A Balance Sheet drilldown can bridge opening balance, activity, and modeled adjustment to the ending Trial Balance.

Filters

An optional single group_by column requests a permitted dimension aggregate.

Example prompt

Show me what is behind the maintenance expense line.

Important details

Handle lifetime. Drilldown handles expire after 24 hours.

Follow the reported number to its supporting evidence.

Does

Pipeline health for every enabled dataset: what is ready, awaiting approval, or blocked, and what the safety checks flagged.

Actions

Call with no arguments to check all enabled datasets. Set mart to check one dataset and run its available diagnostics, for example mart=trial_balance.

Returns

An overall status and a breakdown by dataset: ready, ready with warnings, awaiting approval, blocked, or not yet materialized. Includes reasons, safety-check results, approval status, refresh activity, and evidence of the approved publication being served. Targeted checks add available diagnostic signals and report whether a scan ran and how much data it processed.

Scope

Readiness covers the organization’s enabled datasets. Diagnostic scans examine only rows permitted by this credential’s access, scope, and clearance; any counts describe that authorized slice.

Resources

General Ledger Lines, Trial Balance, Chart of Accounts, Income Statement Lines, Balance Sheet Lines, Cash Flow Components, Cash Flow Statement Lines, Project Overview, Project Financial Position, Business Object Directory, Unit Movements, and Unit Rollforward, as enabled for the organization.

Example prompt

Check every available data product and tell me what is ready now. Flag anything refreshing, awaiting approval, blocked, or still serving an older approved publication. Include the Business Object Directory, and take a closer look at Trial Balance if it is available.

Important details

Diagnostics. Deeper scans are available for General Ledger Lines, Trial Balance, and Chart of Accounts. They surface signals such as unmapped accounts, unbalanced Trial Balance periods, and cash flow classifications needing review. The overall readiness check does not scan dataset tables.

Latest attempt and available data. A failed newer delivery can be blocked while an older approved publication still serves. A refresh in progress is reported separately from a version awaiting approval.

What readiness means. Safety checks verify that PipeLedger’s processing passed its declared controls; they do not validate the source bookkeeping. Publication age is not proof that the source data is current or that month-end close is complete.

Readiness is evidence to check, not an assumption based on when a pipeline last ran.

Does

Reads the organization’s immutable, append-only audit trail for supported pipeline, approval, dataset-lifecycle, and credential-governance events.

Actions

Start with summary for counts across a fixed window, then use events for a focused inspection. Each request covers at most 90 days; event pagination is stable and bound to the filters.

Returns

Event counts in summary mode, or a bounded page of matching audit events with available attribution evidence in events mode.

Scope

The calling credential’s organization and the supported audit-event categories. These are operational records, not financial transaction rows.

Filters

Exact action, governance domain, actor, accountable human, resource, pipeline run, or credential. Actor-context status distinguishes complete, partial, and missing attribution evidence.

Example prompt

Who approved the June publication, and when?

Important details

Access and limits. Raw change payloads and IP or network context are excluded. A configuration-change event alone does not show which values changed or whether access expanded. Audit events describe operations, not General Ledger transactions.

Immutable event evidence, with attribution and explicit limits on what an event proves.

Does

Explains active unit metrics and validates proposed vouchers without posting.

Actions

list_metrics reads metric reference metadata. get_period_status checks one posting period or lists locked periods. validate_voucher checks a proposed voucher.

Returns

Metric definitions, units, movement labels, entry eligibility and period status. Validation reports payload correctness separately from posting permission. Unrestricted unit metric management access adds ERP source bindings.

Scope

Reference metadata is organization-level; voucher validation enforces the connection’s data scope. Enabled Unit Movements or Unit Roll-forward read access includes discovery when permissions are saved; voucher posting also includes it. Existing connections require an explicit access update.

Example prompt

Which unit metrics can we post to this month?

Important details

Preparing a voucher. Discover the exact metric keys for seats, volumes, weight, usage, or other configured operating measures. Check the period and permitted movement types before posting.

Access and limits. Readers can prepare and validate vouchers. Posting requires separate write authority. Validation cannot bypass row filters or reserve a source reference.

Discover the unit registry and its controls before preparing entries.

Does

Refreshes source data through pipelines, publishes approved data to BI, and adds available fields to configured BI delivery. Checks readiness and tracks progress.

Actions

Pipeline: list, preflight, status, and trigger. Pipeline stages are full (extract and build), extract (source data only), and transform (build from existing data). BI: bi_preflight checks available fields and affected sources; bi_publish requests publication, optionally with add_fields; bi_status checks progress.

Returns

Pipeline inventory, readiness checks and run settings, or available BI fields, proposed additions, affected sources and publication progress. Preflight describes current readiness; it does not reserve work or guarantee completion.

Scope

Requires an Operator credential with pl_run enabled. An Owner/Admin must separately enable Add BI fields on the connection for new field selections. Refreshing existing BI selections needs no field-addition grant. Automatic accounting publication has its own permission.

Resources

Pipeline configurations, operational run metadata, organization-enabled data products, and configured BI mart fields. Transform delivery scope belongs to the organization.

Example prompt

Check whether customer names are available for our BI delivery and which configured datasets would change. If permitted, add the field, publish using approved data, and check progress until the update completes.

Important details

Refresh depth. For extraction, sync_mode selects incremental, deep_90d, deep_fiscal_year, or full_refresh. A full pipeline stage is different from a full historical refresh.

Entity context publication. Select only mart_packages=["entity_context"] with stage=transform. It builds saved company and ownership settings without ERP extraction or a General Ledger rebuild. It cannot be combined with financial products. The web equivalent is Run Entity Context in Schemas → Legal entities.

Queue scope. Requests may join existing work. Check the persisted run's marts, force, and automatic-publication settings. For a transform that must stay within the requested settings, bounded=true rejects incompatible joins, including later requests.

BI delivery. Ask which existing mart fields are available, then add them and request publication together. A field selection applies to every configured BI source containing that field. Existing masking and account confidentiality still apply; adding a field does not grant the agent more reading access. Finance Catalog metrics use their separate Deliver in BI selection and activation workflow.

BI refresh and completion. BI refresh uses the latest approved accounting data. Run and approve a pipeline first if newer source data is needed. A queued request is still in progress; use bi_status to confirm publication succeeds and check each source. Your BI tool may also need its field list or cached data refreshed.

Publication and usage. A successful pipeline build may still await approval in Data Review. Automatic accounting publication requires both auto_approve=true and its separate grant. Include a reason when requesting a pipeline run or BI publication. Read actions use FIQ; successful pipeline builds use FCU even when awaiting approval. Unchanged-input skips are uncharged. A BI publication request itself charges nothing; publication work uses FCU according to the work performed.

Ask for a pipeline refresh, a BI field addition, or BI publication; check the corresponding status to confirm the outcome.

Does

Loads, posts, updates, or soft-voids manual vouchers for operating units such as seats, usage, weight, and volume.

Actions

load, post, update, and void. Discover active direct-entry metrics with pl_unit_register first. Load the current voucher before updating; an update replaces its editable header and entries.

Returns

The loaded voucher, validation result, or confirmed write outcome, depending on the action. Write results identify the voucher and its posting period; they do not indicate that unit datasets have been republished.

Scope

Requires explicit Operator posting authority. Update and void additionally require an accountable Owner or Admin. A soft void preserves entries and audit evidence. Dimension scope also restricts the entries the credential may post.

Resources

Manual unit vouchers and their entries for registered direct-entry operating measures. These are separate from General Ledger postings.

Example prompt

Use the attached Stripe subscription report to reconcile new customers, contraction, and expansion, and validate our unit metrics before period close.

Important details

Posting controls. An advisory validate_only dry run, a retry-safe source_ref, optimistic version checks, period locks, dimension scope, and correction linkage. A dry run does not guarantee a later post will succeed.

Publication. Successful changes reach unit datasets through the next successful transform and publication. A missing query result immediately after posting does not mean the voucher was lost.

Access and limits. Never posts to the General Ledger or source ERP. Unit changes can affect per-unit financial ratios, so their effect still matters to reporting.

Audited operating measures that complement the ledger without changing its postings.