Tools and workflows | Finbar Docs

Once you connect Finbar, describe the research task in your conversation. The assistant chooses tools, passes arguments and reads the results. You do not need to write HTTP requests or manage access tokens.

A tool is a named operation, such as list_documents. Its arguments are the inputs it needs, such as the company's entity_id. The tool names below also help you understand the calls shown in your assistant's activity log.

Company and document tools

Tool	Main arguments	Result
`search_entity`	`q`: company name or ticker	Matching companies and their `entity_id` values
`get_entity`	`entity_id`	Company information and identifiers
`list_documents`	`entity_id`; optional document types and period bounds	Reports, their periods and `document_id` values
`search_document`	`query` and exactly one of `entity_id` or `document_id`	Matching paragraphs and tables with item IDs and previews
`read_document`	`item_id`, or `document_id` with `start_index` and `limit`	Paragraph or table content
`get_market_data`	`entity_id`; optional `range` of `2y` or `max`	Available price history and market information

A company record is called an entity. A document item is a paragraph or table within a report. The assistant should use the IDs returned by earlier calls, rather than guess them from a company name or report title.

Research a disclosure

The typical sequence is:

search_entity finds the company ID.
list_documents identifies the relevant reports.
search_document locates matching paragraphs or tables.
read_document reads the source content behind the search previews.

A preview is a short excerpt. Reading the source gives the assistant more context for its answer. Ask it to retain document and item IDs so that you can trace claims back to their sources.

Financial dataset tools

Tool	Main arguments	Result
`get_dataset`	`entity_id`	The current published dataset's ID and metadata
`get_dataset_catalogue`	`entity_id`; optional `expected_dataset_id`	Available metrics, reporting groups, company scopes and periods
`query_dataset`	`entity_id`, `metric_ids`, `scope_combinations`, `periods`	Selected financial values and available source references

The catalogue is the list of financial series you can query. It is needed because metric definitions and company reporting structures vary. See metrics, series and scopes for the data model and reporting periods for fiscal-year conventions.

Retrieve financial history

The assistant should discover the dataset and catalogue before calling query_dataset. It should copy the catalogue's IDs and complete scope paths, and select quarterly periods using their durations.

Dataset query arguments follow the same selection structure as the REST query body, with entity_id added as a tool argument. expected_dataset_id detects publication changes; value_version selects original or latest restated observations.

To check a returned number, ask the assistant to pass its source item_id to read_document. Values and sources explains the result fields.

Results that need more calls

Tool results are bounded, so one call may not contain all matches or all of a report. If a result contains next_cursor, the assistant can repeat the call with that string as cursor, keeping the same target and selections. A cursor is a continuation value; it should be copied unchanged.

Document reads return at most 10 chunks per call. For subsequent document windows, use cursor instead of start_index and keep limit. If is_truncated is true, some returned content was shortened. A table can be read in a smaller range using table_subslice, for example R0C0:R4C3 for rows 0–4 and columns 0–3.

Tool errors

A failed tool call returns an error with a code, message and request_id. The assistant should use the code to decide what to do next.

Code	Next step
`validation_failed`	Correct the tool arguments using the returned field issues
`unauthenticated`	Reconnect to Finbar
`insufficient_scope`	Check the connection's requested permissions
`not_found`	Check the ID and whether the data is available to your account
`dataset_changed`	Fetch the current dataset and catalogue, then rebuild the query
`rate_limit_exceeded`	Wait for `retry_after_seconds` before another call
`service_unavailable`, `internal_error`, `gateway_timeout`	Retry the read after a delay

A prompt can trigger several calls, each using your account's shared request allowance. For a persistent failure, send the request ID and tool name to Finbar support.