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 a directory of governed reporting objects without a search term. review pages through underlying source records and their supporting evidence.

Returns

Candidates with match confidence, ambiguity guidance, relationships, source provenance, and publication evidence. The agent should clarify ambiguous matches before querying.

Scope

Only business objects visible under the calling credential’s access and identity policy. Tokenization preserves directory objects under stable private labels. Plaintext name search can be unavailable without making the underlying data product unavailable.

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.

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 your financial reporting: how metrics are calculated, accounts are classified, and business identities are connected.

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. Assumption and identity workflows are described below.

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, and business-identity governance.

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. Three separate controls apply: Catalog authoring permits drafts and configuration changes. Metric activation additionally permits making metric drafts live. Business identity governance permits reviewed identity-link and role 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.

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

Inspects the organization’s active unit metrics and posting-period locks before a manual unit voucher is prepared.

Actions

list_metrics returns registered metrics, units of measure, balance or flow behavior, allowed movements, direct-entry eligibility, and ERP source bindings. get_period_status returns the requested posting period’s lock state.

Returns

Registered unit metric definitions and source bindings, or the requested posting period’s lock state.

Scope

The organization’s unit registry and period controls. Requires the Units data product and explicit permission to call the tool.

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. Reads configuration; it does not post a voucher.

Discover the unit registry and its controls before preparing entries.

Does

Queues an authorized pipeline run and returns its run identifier. A queued run is not a completed publication.

Actions

full extracts and builds; extract pulls source data only; transform rebuilds from data already in PipeLedger without extracting again.

Returns

The queued run identifier and whether auto-approval was applied. Queueing does not prove the run or publication has completed.

Scope

Requires an Operator credential and explicit permission to call the tool. Auto-approval requires its own additional grant. Running a pipeline is a deliberate action, not a side effect of reading or posting a unit voucher.

Resources

Specific datasets or enabled data-product packages: ledger core, projects, cash flow, units, and Business Intelligence.

Example prompt

Refresh the ledger core for all group entities using incremental updates. Auto-approve and publish the results once the required checks pass. Exclude the cash flow package.

Important details

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

Publication. auto_approve is honored only when the credential has the separate Owner/Admin-granted authority. Otherwise eligible results await Data Review. The response states whether auto-approval was applied.

Audit trail. Include a reason for the pipeline run.

Control extraction, build scope, and release through explicit pipeline authority.

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.