Data & Databases

This page covers the built-in tools that query SQL and graph databases, analyze local data files, work with Google Drive, Docs, Sheets, and BigQuery, and fetch financial market data. Use it to pick a tool, configure its connection, and understand why a tool is unavailable or refused a request.

Choosing a Tool

Setup and Trust

Tools that need a connection or account stay unavailable in the dashboard until their required fields or OAuth connection are stored. Options of type password in the tables below cannot be set inline in config.yaml; see Security Restrictions. db_engine, tables, connection, init_commands, config, csvs, duckdb_connection, duckdb_kwargs, credentials, and obb expect Python objects, lists, or mappings, so they cannot be set usefully from config.yaml or the dashboard. sql, postgres, redshift, duckdb, csv, and pandas can read or write local files that the agent's file_access setting does not confine, and sql, duckdb, and pandas always run in the primary runtime, so enable them only for agents you trust with what the MindRoom process can reach; see File access. The Google tools connect through per-service OAuth; see Google Services OAuth For Local Installs or Google Services OAuth for custom and hosted setups. Missing Python dependencies install automatically on first use; see Automatic Dependency Installation.

[sql]

sql provides list_tables(), describe_table(table_name), and run_sql_query(query, limit=10). run_sql_query() returns 10 rows unless the call passes another limit, or limit=None for all rows. Connect with db_url, or let MindRoom assemble a URL from dialect, user, password, host, port, and schema. The assembled URL uses schema as the database name and also as the schema for table inspection, so use db_url for dialects where those differ. For PostgreSQL or Redshift, the dedicated postgres and redshift tools add query plans and exports.

[postgres]

postgres provides show_tables(), describe_table(), summarize_table(), inspect_query(), run_query(), and export_table_to_path(). The connection is read-only, so queries cannot modify the database. inspect_query() runs EXPLAIN, which is a cheap check before a large run_query(). export_table_to_path() writes a table as CSV to a path on the machine running MindRoom.

agents:
  warehouse:
    tools:
      - postgres:
          host: warehouse.internal
          db_name: analytics
          user: analyst
          table_schema: reporting

[redshift]

redshift provides the same functions as postgres: show_tables(), describe_table(), summarize_table(), inspect_query(), run_query(), and export_table_to_path(). It authenticates with user and password, or with IAM through an AWS profile or explicit AWS keys when iam: true. Unset fields can fall back to the environment variables REDSHIFT_HOST, REDSHIFT_DATABASE, REDSHIFT_DB_USER, REDSHIFT_CLUSTER_IDENTIFIER, AWS_REGION, and AWS_PROFILE. The dashboard treats user and password as required even when iam is enabled, so store values for both before the tool becomes available.

agents:
  warehouse:
    tools:
      - redshift:
          host: my-cluster.abc123.us-east-1.redshift.amazonaws.com
          database: dev
          user: analyst
          table_schema: reporting

[neo4j]

neo4j provides list_labels(), list_relationship_types(), get_schema(), and run_cypher_query(). Set enable_run_cypher: false to give an agent schema visibility without free-form graph queries.

agents:
  graph:
    tools:
      - neo4j:
          uri: bolt://graph.internal:7687
          user: neo4j
          database: analytics
          enable_run_cypher: false

[duckdb]

duckdb is the best choice for repeatable local analytics over files. It provides show_tables(), describe_table(), inspect_query(), run_query(), summarize_table(), create_table_from_path(), export_table_to_path(), load_local_path_to_table(), load_local_csv_to_table(), load_s3_path_to_table(), load_s3_csv_to_table(), create_fts_index(), and full_text_search(). Without db_path, the database lives in memory and is not saved. export_table_to_path() writes Parquet unless the call passes another format such as CSV.

agents:
  analyst:
    tools:
      - duckdb:
          db_path: data/analytics.duckdb

create_table_from_path("/workspace/data/orders.parquet", table="orders", replace=True)
run_query("SELECT customer_id, COUNT(*) AS orders FROM orders GROUP BY 1 ORDER BY orders DESC LIMIT 10")
export_table_to_path("orders", format="CSV", path="/tmp")

[csv]

csv provides list_csv_files(), read_csv_file(), get_columns(), and query_csv_file() over a pre-registered list of CSV files, each named by its filename stem. config.yaml and the dashboard accept csvs only as a string, so they cannot register a file list and the tool has no files to read; use duckdb to query CSV files. query_csv_file() runs only the first SQL statement it receives.

[pandas]

pandas provides create_pandas_dataframe() and run_dataframe_operation(). create_pandas_dataframe() calls a Pandas constructor such as read_csv or read_json and stores the result under a name, rejecting empty dataframes and names already in use. run_dataframe_operation() calls a dataframe method such as head, describe, or groupby on a stored dataframe. Dataframes live only in memory and are lost on restart.

create_pandas_dataframe("sales", "read_csv", {"filepath_or_buffer": "/workspace/data/sales.csv"})
run_dataframe_operation("sales", "describe", {})

[google_bigquery]

google_bigquery provides list_tables(), describe_table(), and run_sql_query() for the configured dataset. The dataset is only the default for unqualified table names, so queries can still reference other datasets that the Google Cloud credentials can read. It authenticates with the MindRoom process's default Google Cloud credentials, not with MindRoom's Google OAuth connections.

agents:
  analyst:
    tools:
      - google_bigquery:
          project: my-gcp-project
          dataset: analytics
          location: US

[google_drive]

google_drive works with files in the connected Google account, including shared drives the account can access.

Non-Workspace files over max_read_size return an error suggesting google_drive_download_file instead. Downloads larger than max_download_size are refused without leaving a partial file. Uploads and content replacement read local files according to the agent's file_access setting. Downloads need an agent workspace; for an agent without one, download_file is ignored and a warning is logged. To change the content of a native Google Doc, use google_docs. If the account is not connected, the tool returns an OAuthConnectionRequired result with a connect link; see Google Services OAuth For Local Installs. A connection that granted only read-only Drive access keeps working for reads, while writes ask the user to reconnect; see Scope Rationale.

To require a person to approve each Drive change, add Tool Approval rules:

tool_approval:
  rules:
    - match: google_drive_upload_file
      action: require_approval
    - match: google_drive_update_file
      action: require_approval
    - match: google_drive_create_folder
      action: require_approval
    - match: google_drive_move_file
      action: require_approval
    - match: google_drive_trash_file
      action: require_approval

[google_docs]

google_docs creates, reads, and edits Google Docs through its own OAuth connection, separate from Google Drive.

Each document_id accepts either a document ID or a full Google Docs URL. Every successful call returns the document's edit URL. If the account is not connected, the tool returns an OAuthConnectionRequired result with a connect link. Before public production use, the Docs scope needs Google verification; see Production Verification Follow-up.

[google_sheets]

google_sheets provides read_sheet(spreadsheet_id=None, spreadsheet_range=None), create_sheet(title), update_sheet(data, spreadsheet_id=None, range_name=None), and batch_update_sheet(spreadsheet_id, requests). When spreadsheet_id or spreadsheet_range is configured, read_sheet() always uses it and ignores the value passed in the call, so leave both unset to read from many spreadsheets. update_sheet() ignores both settings and needs an explicit spreadsheet_id and range_name on every call. update_sheet() writes values literally, so a formula such as =SUM(A1:A3) is stored as text and does not calculate. batch_update_sheet() sends Sheets API batchUpdate requests in order, for changes such as cell formatting, column widths, frozen rows, filters, and adding or renaming sheets. batch_update_sheet() can also delete sheets, rows, and ranges, and a Tool Approval rule for update_sheet does not match it; a *update_sheet rule matches both, including the prefixed names of additional Google workspace accounts. The tool is available only once the stored Google Sheets connection includes the Sheets scope; if the account is not connected, calls return an OAuthConnectionRequired result with a connect link.

agents:
  ops:
    tools:
      - google_sheets:
          spreadsheet_id: 1AbCdEfGhIjKlMnOpQrStUvWxYz
          spreadsheet_range: Sheet1!A1:G200

[openbb]

openbb provides get_stock_price(symbol), search_company_symbol(), get_company_news(symbol, num_stories=10), get_company_profile(), and get_price_targets(). Symbols can be comma-separated, such as AAPL,MSFT. The default yfinance provider works without an OpenBB account; set openbb_pat or the OPENBB_PAT environment variable for premium providers. Choose openbb over yfinance when you need to switch data providers.

agents:
  market:
    tools:
      - openbb:
          enable_search_company_symbol: true
          enable_get_company_news: true

[yfinance]

yfinance reads Yahoo Finance data with no credentials. Only the current stock price is enabled by default, so enable each additional function the agent needs.

agents:
  market:
    tools:
      - yfinance:
          enable_company_info: true
          enable_historical_prices: true
          enable_company_news: true

[financial_datasets_api]

financial_datasets_api reads structured data from Financial Datasets through get_income_statements(), get_balance_sheets(), get_cash_flow_statements(), get_segmented_financials(), get_financial_metrics(), get_company_info(), get_stock_prices(), get_earnings(), get_insider_trades(), get_institutional_ownership(), get_news(), get_sec_filings(), get_crypto_prices(), and search_tickers(). Set api_key or the FINANCIAL_DATASETS_API_KEY environment variable; without a key, every call returns API key not set.

Related Docs

• Tools Overview
• Per-Agent Tool Configuration
• Google Services OAuth For Local Installs
• Google Services OAuth