# Tools and workflows Understand which Finbar tools your assistant calls and how they work together. Source: Once you [connect Finbar](https://docs.finbar.com/api-mcp/mcp.md), 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 > **Example prompt** > > Use Finbar to find Apple and its recent annual reports. Find the discussion of revenue growth, read the relevant passages, and summarize management's explanation with source references. The typical sequence is: 1. `search_entity` finds the company ID. 2. `list_documents` identifies the relevant reports. 3. `search_document` locates matching paragraphs or tables. 4. `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](https://docs.finbar.com/api-mcp/datasets.md) for the data model and [reporting periods](https://docs.finbar.com/api-mcp/periods.md) for fiscal-year conventions. ### Retrieve financial history > **Example prompt** > > Use Finbar to find Apple's revenues by product line for the past 12 quarters, including source references. 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](https://docs.finbar.com/api-mcp/dataset-query.md#build-the-request), 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](https://docs.finbar.com/api-mcp/values.md) 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](https://docs.finbar.com/api-mcp/usage.md). For a persistent failure, send the request ID and tool name to [Finbar support](https://docs.finbar.com/web/support.md).