Skip to main content
Agents interact with your repository and data warehouse through tools—functions that read files, run queries, execute commands, and perform operations. This guide covers what tools are available and how to use them effectively.

​
How Tools Work

When an agent runs, it has access to a set of tools it can use to accomplish the task defined in your prompt. The agent decides which tools to use based on your instructions. For example, if your prompt says “read the model file and update its documentation,” the agent will:
  1. Use the Read tool to get the file contents
  2. Use the Edit tool to update the documentation
  3. Use Bash to commit and push the changes
You don’t need to specify which tools to use—just describe what you want done, and the agent figures out how to do it.

​
Available Tools

​
File Operations

​
Read
tool
Read the contents of files in the repository.Capabilities:
  • Read any file in the repository
  • Read multiple files
  • Access file metadata
Example prompt usage:
prompt: |
  Read the model file at models/marts/customers.sql
  and analyze its structure.
​
Write
tool
Create new files or overwrite existing files.Capabilities:
  • Create files in any directory
  • Create parent directories as needed
  • Overwrite existing files
Example prompt usage:
prompt: |
  Create a new YAML documentation file for the customers model
  at models/marts/_customers.yml
​
Edit
tool
Modify existing files using search-and-replace operations.Capabilities:
  • Find and replace text patterns
  • Multi-line edits
  • Preserve file formatting
Example prompt usage:
prompt: |
  Update the description field in the customers.yml file
  to include the new column information.
​
Grep
tool
Search file contents using patterns.Use for:
  • Finding specific code patterns
  • Locating model references
  • Searching across the codebase
Example prompt usage:
prompt: |
  Search for all models that reference the customers table
  using ref('customers').
​
Glob
tool
Find files matching path patterns.Example patterns:
  • models/**/*.sql — All SQL files in models
  • models/marts/**/dim_*.sql — All dimension models
  • **/*.yml — All YAML files
Example prompt usage:
prompt: |
  Find all staging models (files matching models/staging/**/*.sql)
  and check their documentation status.
​
LS
tool
List directory contents.Capabilities:
  • List files and subdirectories
  • Get file metadata
  • Explore directory structure
Example prompt usage:
prompt: |
  List all files in the models/marts directory
  to understand the project structure.

​
Data Access

​
RunSql
tool
Execute SQL queries against your connected data warehouse.Capabilities:
  • Run SELECT queries
  • Join across schemas
  • Aggregate and transform data
Example prompt usage:
prompt: |
  Query the customers table to understand its structure:
  SELECT column_name, data_type 
  FROM information_schema.columns 
  WHERE table_name = 'customers'
Queries are read-only by default. The agent can analyze data but cannot modify tables.
​
RetrieveMetadata
tool
Get table and column statistics without running queries. Faster and more efficient than SQL for profiling.Returns:
  • Row counts
  • Column names and types
  • Null percentages
  • Distinct value counts
  • Min/max for numeric columns
  • Sample values
Example prompt usage:
prompt: |
  Use RetrieveMetadata to profile the customers model.
  Include null rates and distinct counts in the documentation.
Prefer RetrieveMetadata over RunSql for profiling tasks—it’s faster and costs less in warehouse compute.
​
DataDiff
tool
Compare the results of two SQL queries to identify differences at the row level.Returns:
  • Row counts for both queries
  • Rows only in the first query (removed)
  • Rows only in the second query (added)
  • Rows with matching keys but different values (changed)
  • Sample rows illustrating each type of difference
Example prompt usage:
prompt: |
  Compare the original and modified versions of this query.
  Use DataDiff to identify:
  - How many rows were added or removed
  - Which values changed and why
  - Sample differences to include in the review
Key columns:The tool uses key columns to match rows between the two result sets. You can specify key columns explicitly, or the tool will infer them from primary keys or common ID columns.
prompt: |
  Run a data diff between the old and new query results.
  Use user_id as the key column for matching rows.
  Show me sample rows that changed so I can understand the impact.
DataDiff runs both queries and compares results in memory. For large result sets, add filters to scope the comparison to a representative sample.

​
Command Execution

​
Bash
tool
Execute shell commands in the repository environment.Common commands:
  • git — Git operations (add, commit, push, branch)
  • gh — GitHub CLI (create PRs, post comments)
  • dbt — dbt commands (parse, compile, run)
  • python — Python scripts
Example prompt usage:
prompt: |
  After updating the documentation:
  1. Run dbt parse to validate the YAML
  2. Commit the changes with a descriptive message
  3. Create a PR using gh pr create

​
Optional Tools

Some tools must be explicitly enabled in your agent configuration.
​
slack_tool
optional tool
Send messages to Slack channels. Requires Slack integration to be configured in the Buster platform.Enable in agent config:
tools:
  include:
    - slack_tool
Example prompt usage:
prompt: |
  Send a summary of the documentation updates to #data-team on Slack.
  Include the list of models that were updated.
The Buster bot must be invited to the channel before it can post messages.

​
Git Operations

Agents perform Git operations through the Bash tool using standard Git and GitHub CLI commands.

​
Common Patterns

Creating a branch and committing: 
prompt: |
  After making changes:
  1. Create a branch: git checkout -b docs/update-customers
  2. Stage changes: git add .
  3. Commit: git commit -m "docs: Update customers model documentation"
  4. Push: git push -u origin docs/update-customers
Creating a pull request: 
prompt: |
  Create a PR with your changes:
  gh pr create \
    --title "docs: Update model documentation" \
    --body "Automated documentation update by Buster"
Posting a PR comment: 
prompt: |
  Post a comment on the PR summarizing your findings:
  gh pr comment $PR_NUMBER --body "Your comment here"

​
Auto-Commit Behavior

For pull request triggers, the auto_commit field controls how changes are committed:
SettingBehavior
auto_commit: false (default)Creates a new branch and opens a new PR
auto_commit: trueCommits directly to the PR branch
triggers:
  - event: pull_request
    auto_commit: false  # Safe: creates separate PR
Use auto_commit: true with caution—it can cause merge conflicts if multiple people are working on the same PR.

​
Security Model

Agents run in isolated Daytona sandboxes—secure cloud environments with controlled access:

​
What Agents Can Access

  • Your repository — Full read/write access to files
  • Your data warehouse — Query access via configured credentials
  • GitHub API — Create PRs, post comments, update check runs
  • Slack — Send messages (if slack_tool enabled)

​
What Agents Cannot Access

  • The internet — No general network access (only GitHub and Buster APIs)
  • Other repositories — Only the triggered repository
  • Persistent state — Each run is independent; no state persists between runs
  • Your local machine — Agents run in cloud sandboxes, not locally

​
Credential Handling

  • Data warehouse credentials are injected securely from the Buster platform
  • GitHub tokens are scoped to the specific repository
  • API keys and secrets are never logged or exposed
  • All credentials are encrypted at rest

​
Best Practices

​
Write Clear Prompts

Be explicit about what tools you expect the agent to use: 
# Vague
prompt: Check the model

# Clear
prompt: |
  1. Read the SQL file at models/marts/customers.sql
  2. Use RetrieveMetadata to get column statistics
  3. Update the YAML documentation with accurate descriptions
  4. Run dbt parse to validate the changes

​
Use the Right Tool

TaskBest Tool
Get column statisticsRetrieveMetadata
Run custom analysis queriesRunSql
Compare query resultsDataDiff
Find files by patternGlob
Search file contentsGrep
Validate dbt projectBash with dbt parse
Create PRsBash with gh pr create

​
Handle Errors in Prompts

Tell the agent what to do when things go wrong: 
prompt: |
  Update documentation for the changed models.
  
  If dbt parse fails:
  - Do NOT commit the changes
  - Post the error as a PR comment
  - Stop without creating a PR
  
  If the warehouse is unreachable:
  - Post a comment explaining the issue
  - Proceed with documentation based on SQL analysis only

​
Minimize Warehouse Queries

Use RetrieveMetadata instead of RunSql when possible: 
# Efficient: Uses cached metadata
prompt: |
  Use RetrieveMetadata to profile each model's columns.

# Expensive: Runs queries against warehouse
prompt: |
  Run SQL queries to count distinct values for each column.