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
`get_account_permissions`	None	Effective document read allowances for your account
`search_entity`	`q`: company name or ticker	Matching companies and their `entity_id` values
`get_entity`	`entity_id`	Company information and identifiers
`get_entity_wiki`	`entity_id`; optional `types`	Saved overview, products, geography, segments, and history sections
`search_entity_wiki`	`query`; optional `types`, `limit`, `cursor`	Keyword discovery across saved company wikis, with section previews and ten-minute pagination
`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.

Get a company overview

Ask: "Use Finbar's company wiki to explain Apple's business and products." The assistant first calls search_entity, then get_entity_wiki with types: ["OVERVIEW", "PRODUCTS"]. Omitted or empty types returns all available sections. This tool requires read and reads saved descriptions; it does not generate or refresh them. It preserves inline citations. Reading the cited document content separately requires read.

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.

Watchlists

manage_watchlists is the single tool for listing, inspecting, creating, renaming and deleting personal watchlists and adding/removing companies. Its action argument selects the operation. Reads need read; mutations need read and write. See watchlist arguments and concurrency.

Dataset build and update tools

build_dataset populates a supplied row list; update_dataset refreshes explicit historical periods using an existing model. Both start asynchronous work that consumes AI credits. Use get_dataset_run, cancel_dataset_run and get_dataset_result to manage the run and retrieve bounded JSON pages. See dataset inputs, charges and recovery before starting work.

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.

Use get_account_permissions to discover your effective document read allowance. Free and personal plans allow 10 chunks per call; Enterprise allows 100, subject to account overrides. Responses also include limits. Each chunk normally has a 10,000-character cap, excluding the abbreviation notice. 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.

Set disable_truncate: true with item_id only when you specifically need the full text of a previously truncated item. It defaults to false and cannot be used with document windows.

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

Ask: "Find companies whose wiki describes semiconductor manufacturing equipment." The assistant calls search_entity_wiki, then get_entity_wiki for complete sections and citations. See wiki search for filters, ranking, and pagination limits.