Selecting the right tools

Available tools:

Tool What It Does
GetUserSpaces Lists Birst workspaces the current user has access to
SearchSpaceSubjectAreaContent Discovers measures and attributes available in a workspace
GenerateBqlQuery Converts a natural language question into a BQL query
ExecuteBqlQuery Runs a BQL query and returns data results
CreateReport Generates a link to create a new report in Birst Visualizer
SearchSpaceCatalog Searches existing reports and dashboards and returns navigable links

You do not need to add all tools to every agent. Select the right tool based on what your agent needs to do:

  • Your workspace is known (most common). If the agent always works with a specific workspace, for example a Sales or Finance workspace, hardcode the workspace ID in the agent instructions and use:
    • SearchSpaceSubjectAreaContent
    • GenerateBqlQuery
    • ExecuteBqlQuery
    • CreateReport: optional, if users need report links
    Note: No need for GetUserSpaces when the workspace is already known.
  • Your workspace is not known. If users might ask about different workspaces and the agent needs to find the right one:
    • GetUserSpaces
    • SearchSpaceSubjectAreaContent
    • GenerateBqlQuery
    • ExecuteBqlQuery
  • You want to find existing content. If users want to generate reports in Visualizer from natural language:
    • CreateReport

Recommended workflow

The typical flow an agent follows when you ask a question:

Step Tool Purpose
1 GetUserSpaces Find the correct workspace, omit if workspace ID is known
2 SearchSpaceSubjectAreaContent Discover what measures and attributes are available
3 GenerateBqlQuery Convert the user's question into a BQL query
4 ExecuteBqlQuery Run the query and get data back
5 SearchSpaceCatalog Optional: Find an existing report that answers the question
6 CreateReport Optional: Generate a link for the user to visualize results

Writing effective Agent instructions

Clear instructions help the agent make accurate decisions and complete tasks efficiently. Use these guidelines:

  • Specify the workspace ID. If the workspace ID is available, include it in the instructions. The workspace ID reduces lookup requests and improves accuracy.
  • Define the workflow sequence. Specify which tools the agent must use and the order in which the agent must use them.
  • Set query result limits. Define a maximum number of records to return. For example, specify: "Set a limit of 100 rows for all queries."
  • Provide data context. Describe the type of data that the workspace contains. Data context helps the agent interpret user requests accurately.

Example: Known workspace with a clear workflow.

  1. Use workspace ID 3ac379d4-ba63-4c32-98a6-201ff002dfb8 for all tool calls. Do not use GetUserSpaces.
  2. When you ask a data question, first call SearchSpaceSubjectAreaContent to identify relevant measures, then call GenerateBqlQuery followed by ExecuteBqlQuery.
  3. Always set a row limit of 100 on ExecuteBqlQuery.
  4. If you ask to visualize results, call CreateReport and return the link as-is.
  5. If you ask to find an existing report, use SearchSpaceCatalog.

Things to remember:

  • Birst AI Tools respect user permissions. The agent can access workspaces and data that the current user has permission to view.
  • The agent uses measures and attributes that are enabled in GenAI Settings (Data Model Descriptions). If a field is not enabled in GenAI Settings, the agent cannot use the field, even when the field exists in the workspace.
  • The CreateReport tool returns a link that opens Birst Visualizer. The tool does not return data. Return the link to the user without modification.
  • An agent supports a maximum of 10 tools from all sources.
  • Result quality depends on how the workspace's Data Model Descriptions are configured, including labels, descriptions, and embeddings.
  • Start with a focused configuration. Add three or four tools for a specific use case instead of adding all tools at the same time. Fewer tools produce more predictable agent behavior.
  • Specify workspace IDs in agent instructions when possible. A fixed workspace ID removes a processing step and improves reliability.
  • Test the agent before publication. Use GenAI Chat to test the agent with different questions before you make the agent available to end users.
  • Configure Data Model Descriptions before you configure the agent. Query accuracy depends on labels, descriptions, embeddings, and enabled elements in the workspace's GenAI Settings.
  • Set row limits. Instruct the agent to limit query results to prevent large outputs.
  • Keep instructions concise. Use clear, numbered workflow steps instead of long paragraphs.