Docs/System & Configuration/Tools Reference

Tools Reference

Complete reference for all query, reporting, and write tools available through the conversational interface

12 min read

Overview#

Artifi provides a unified set of tools for querying, analyzing, and modifying your financial data through natural conversation. These tools cover 59 entity types across all financial domains -- from vendors and invoices to fixed assets and recurring contracts.

Tool Inventory#

Tool	Purpose	Type
`search`	Free-text search across entities	Read
`get_entity`	Get a single entity by ID	Read
`list_entities`	Paginated list with filters	Read
`batch_lookup`	Fetch multiple entity types in one call	Read
`aggregate_entities`	GROUP BY analytics (sum, count, avg)	Read
`generate_report`	Formal financial and operational reports	Read
`list_report_types`	Discover available reports	Read
`submit`	Create, update, and delete via workflows	Write

Plus 8 workflow management tools for approval tasks, and 5 domain gateway tools for imports, onboarding, organization admin, banking connectors, and agent management.

Total: 34 tools covering all financial operations.

Tool Selection Guide#

I want to...	Use	Why?
Find records by name or text	`search`	Text matching across configurable search fields
Get one record with full details	`get_entity`	Includes related entities (addresses, lines, etc.)
List records with filtering and pagination	`list_entities`	Date ranges, sorting, page navigation
Fetch reference data before a create/update	`batch_lookup`	Replaces 3-5 sequential lookups in one call
Get totals, counts, or trends	`aggregate_entities`	Ad-hoc GROUP BY analytics
Generate formal financial statements	`generate_report`	Standard accounting formats with full detail
Discover which reports exist	`list_report_types`	Browse by category
Create, update, or delete records	`submit`	All writes go through workflow validation and audit

Search vs. List#

Scenario	Tool
"Find vendor named Acme"	`search`
"All pending bills for entity 10"	`list_entities`
"Transactions from January 2025"	`list_entities` with date filters
"Search transactions mentioning AWS"	`search`

Aggregate vs. Report#

Scenario	Tool
"Total spend by vendor"	`aggregate_entities`
"Monthly revenue trend"	`aggregate_entities` with time bucketing
"Trial balance as of Dec 31"	`generate_report`
"AP aging report"	`generate_report`

Rule of thumb: Use aggregate_entities for quick ad-hoc questions. Use generate_report for formal financial statements with standard accounting formatting.

Search#

Free-text search across configurable fields for any entity type. Returns up to 100 results with optional line items.

Key behaviors:

Searches different fields depending on entity type (e.g., vendors search name, email, tax ID, phone, website, and notes)
Warns you if your query looks like a date -- use list_entities with date filters instead
Can include line items in a single batch query (not N+1)
Invalid filter fields are ignored with warnings in the response

Get Entity#

Retrieve a single entity by numeric ID or global ID, with optional related entities loaded automatically.

Supported global ID lookups:

Entity Type	Global ID Example
Vendor	`VEND-000123`
Customer	`CUST-000456`
Employee	`EMP-000789`
Item	`ITEM-000001`
Project	`PROJ-000001`
Bank Statement	`BS-2025-001`
Agent Definition	`bill_processor`
Expense Report	`EXP-000001`
Payment Batch	`PAY-000001`
Connector	`wise_usd`
Transaction Type	`AP_INVOICE`

Key behaviors:

Related entities (addresses, bank accounts, lines, dimensions) are fetched by default
If one related query fails, others still return successfully
UUID-based entities (agent instances, events, requests, sagas) accept UUID strings as IDs

List Entities#

Paginated listing with flexible filtering, date ranges, sorting, and optional line items.

Key behaviors:

Full pagination metadata: total count, total pages, has next/previous
Date range filters with from, to, or both
Sort by any configured field in ascending or descending order
Line items loaded in a single batch query when requested
Virtual fields (like vendor name on bills) resolved automatically

Batch Lookup#

Fetch multiple entity types in a single call. Ideal for gathering reference data before creating or updating records.

Constraints:

Constraint	Value
Max queries per call	10
Max results per sub-query	100
Single database connection	Yes (efficient)

Key behaviors:

One sub-query failure does not block others
All sub-queries execute on a single database connection for efficiency
Perfect for loading payment terms, tax codes, dimension types, and accounts before posting a transaction

Aggregate Entities#

Ad-hoc GROUP BY analytics across entity types. Group by up to 3 columns with sum, count, average, min, and max functions.

Supported entity types: Transactions, bills, bank statement lines, card transactions, fixed assets, recurring contracts, budget lines, expense reports, payment batches, depreciation runs, and billing runs.

Time Bucketing#

Add a time_bucket to group results by day, week, month, quarter, or year. Results include a period column for charting and trend analysis.

Aggregate Functions#

Function	Result Column	Description
`sum`	`sum_{column}`	Sum of values
`count`	`count_{column}`	Count of rows
`count_distinct`	`count_distinct_{column}`	Count of unique values
`avg`	`avg_{column}`	Average
`min`	`min_{column}`	Minimum
`max`	`max_{column}`	Maximum

Results include a totals row with aggregated values across all groups.

Generate Report#

Formal financial and operational reports with standard accounting formats. Use list_report_types to discover all available reports.

Report Categories#

Financial Reports

Report	Key Parameters
Trial Balance	Entity, as-of date
Balance Sheet	Entity, as-of date
Income Statement	Entity, date range
Cash Flow Statement	Entity, date range
Account Activity	Entity, account, date range
General Ledger Detail	Entity, date range
Statement of Changes in Equity	Entity, date range
AR Aging	Entity, as-of date
AP Aging	Entity, as-of date
Vendor Aging Detail	Entity, vendor, as-of date

Consolidated Reports

Report	Key Parameters
Consolidated Trial Balance	Multiple entities, as-of date
Consolidated Balance Sheet	Multiple entities, as-of date
Consolidated Income Statement	Multiple entities, date range
Entity Comparison	Multiple entities, date range

Tax Reports

Report	Key Parameters
Sales Tax Summary	Entity, date range
Tax Filing Worksheet	Entity, period
VAT Report	Entity, date range
1099 Report	Entity, tax year

Operational Reports

Report	Key Parameters
Revenue by Customer	Entity, date range
Revenue by Item	Entity, date range
Expense by Vendor	Entity, date range
Expense by Category	Entity, date range
Deferred Revenue	Entity, as-of date
Prepaid Expense	Entity, as-of date

Banking Reports

Report	Key Parameters
Cash Position	Entity
Cash Forecast	Entity, forecast days
Reconciliation Summary	Entity
Outstanding Reconciliation Items	Entity, bank account

SaaS Metrics

Report	Key Parameters
Monthly Recurring Revenue (MRR)	Entity, as-of date
Annual Recurring Revenue (ARR)	Entity, as-of date
Churn	Entity, date range

Submit (Write Operations)#

Universal gateway for all create, update, and delete operations. Every write goes through the workflow system for validation, authorization, and audit trail.

Common Operations#

Object Type	Operations
Vendor	create, update, delete
Customer	create, update, delete
Employee	create, update, delete, reactivate
Transaction	post, reverse
Fixed Asset	create, update, acquire from bill, dispose, transfer, impair
Bank Account	create, update, delete, verify
Expense Report	create, update, submit, approve, reject, cancel
Payment Batch	create, approve, execute
Card	issue, activate, suspend, cancel

Transaction Types#

All financial transactions use a unified transaction type system:

Transaction Type	Description
`AP_INVOICE`	Vendor bill
`AR_INVOICE`	Customer invoice
`AP_PAYMENT`	Vendor payment
`AR_RECEIPT`	Customer receipt
`JOURNAL_ENTRY`	Manual journal entry
`BANK_TRANSFER`	Bank-to-bank transfer

Key behaviors:

All inputs validated via structured models before execution
Risk-based workflow routing: Green (auto-approve), Yellow (single approval), Red (multi-level)
Complete audit trail for every operation
Operations run inside database transactions for safety

Workflow Management Tools#

Tools for managing approval workflows and tasks:

Tool	Purpose
My Tasks	Get tasks assigned to you, filtered by status
Task Details	See the full payload, history, and comments for a task
Complete Task	Approve or reject a workflow task
Edit Payload	Modify workflow data fields before approval
Add Comment	Attach notes to a workflow
Workflow History	Full audit trail of events, decisions, and comments
Get Schema	Discover required and optional fields for any workflow type
Import Status	Track progress of bulk import operations

Domain Gateway Tools#

Five domain gateways consolidate specialized operations:

Gateway	Purpose	Key Actions
Imports	Bulk data import	Accounts, customers, vendors, employees, transactions, fixed assets, items, dimensions
Onboarding	Entity setup and configuration	Check status, run setup waves, load demo data, download skills
Organization	Org administration	Get info, switch org, manage roles, manage plugins, create client orgs
Connectors	Banking integrations	Register, activate, sync statements, manage credentials
Agents	AI agent management	Configure agents, manage events, view instances, manage memory

Entity Type Quick Reference#

Master Data#

Type	Search Fields	Key Filters
Vendor	Name, email, tax ID, phone, website	Entity, active status, vendor type, payment terms
Customer	Name, email, tax ID, phone, website	Entity, active status, customer type, payment terms
Employee	First/last name, email, job title, department	Entity, status, department, location
Item	Name, number, description, category	Entity, active status, item type

Transactions#

Type	Search Fields	Key Filters
Transaction	Number, description, reference, party ID	Entity, type, status, party, fiscal period
Bill	Number, description, reference	Entity, status, vendor, currency
Expense Report	Report number, title, notes	Entity, employee, status
Payment Batch	Batch number, payment method	Entity, status, payment method

Fixed Assets#

Type	Search Fields	Key Filters
Fixed Asset	Asset number, name, serial number, location	Entity, status, category, depreciation method
Asset Category	Code, name, description	Active status, depreciation method

Banking#

Type	Search Fields	Key Filters
Bank Account	Code, name, bank name, account number, IBAN	Entity, currency, account type
Bank Statement	Statement number	Entity, bank account, status, date
Statement Line	Description, reference	Entity, bank account, reconciliation status

Configuration#

Type	Search Fields	Key Filters
Account	Number, name, description	Entity, type, subtype, active status
Legal Entity	Code, name, tax ID	Active status, currency, country
Fiscal Period	Period name	Entity, year, closed status
Tax Code	Code, name, description	Active status, tax type
Dimension Type	Name, display name	Active status, required flag

← PreviousRoles & Permissions Next →Automatic Numbering

Subscribe to new posts

Get notified when we publish new insights on AI-native finance.