Available Tools
The AI agent has a set of tools it uses to find, understand, and query your data. The agent autonomously decides which tools to use based on your question.
┌──────────────────────────────────────────────────────────────────┐
│ Agent Tool Pipeline │
├──────────────────────────────────────────────────────────────────┤
│ │
│ "What were top products by revenue?" │
│ │ │
│ ├──────────────────────────┐ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌───────────────────┐ │
│ │search_tables │ │search_dashboards │ │
│ └──────┬───────┘ └────────┬──────────┘ │
│ │ tables: orders, │ found: "Revenue Dashboard" │
│ │ products, revenue_agg │ → suggest existing dashboard│
│ ▼ ▼ │
│ ┌──────────────┐ get columns, types, samples │
│ │describe_table│──▶ returns: full schema + sample rows │
│ └──────┬───────┘ │
│ ▼ │
│ ┌──────────────┐ SELECT product, SUM(revenue) ... │
│ │execute_query │──▶ returns: structured result (≤10K rows) │
│ └──────┬───────┘ │
│ ▼ │
│ 📊 Chart / 📋 Table / 💬 Answer │
│ (consistent with existing dashboards) │
│ │
└──────────────────────────────────────────────────────────────────┘Core Tools
search_tables
Searches the data catalog for tables matching keywords or descriptions.
When it's used: The agent calls this first to discover which tables are relevant to your question. It uses semantic matching against table names, column names, and AI-generated descriptions.
Returns: A list of matching tables with their schemas, descriptions, and relevance scores.
Example: For the question "How many users signed up last month?", the agent might search for keywords like "users", "signups", "registrations".
search_dashboards
Searches existing dashboards in the organization for ones that already answer the user's question.
When it's used: The agent calls this alongside search_tables to check if an existing dashboard already covers the requested data. This prevents creating duplicate dashboards and ensures answers are consistent with what the organization already has.
Returns: A list of matching dashboards with their titles, descriptions, contained metrics, and direct links.
Example: For the question "Show me Total Revenue trend in 2025", the agent searches for dashboards related to "revenue", "total revenue", "2025". If it finds a "2025 Sales Dashboard" that already has a Monthly Revenue trend chart, it references that dashboard directly instead of building a new query from scratch.
Why this matters:
- No duplicated dashboards — the agent suggests existing dashboards instead of creating new ones for every question
- Consistent results — answers reference the same established SQL queries and metrics your team already uses
- Dashboard modifications over creation — when a dashboard almost covers what's needed, the agent suggests adding or modifying cells rather than spawning a new dashboard
describe_table
Retrieves full metadata for a specific table.
When it's used: After finding candidate tables via search_tables, the agent calls this to get detailed information about a specific table before writing a query.
Returns:
- Column names and data types
- Sample data (first few rows)
- Indexes and foreign keys
- AI-generated column descriptions
- Row count
execute_query
Runs a SQL query against a connected database and returns the results.
When it's used: Once the agent has identified the right tables and written a SQL query, it executes it with this tool.
Parameters:
- SQL query string
- Connector ID (which database to run against)
Returns: Query results as structured data (up to 10,000 rows), with column names and types.
Safety features:
- All queries run with read-only permissions
- Query timeout: 2 minutes
- Results are paginated (1,000 rows per page)
- Results are cached in S3 for later retrieval
list_connectors
Lists all database connectors available in the organization.
When it's used: When the agent needs to determine which databases are available or select the right connector for a query.
Returns: Connector names, types, and IDs.
query_popularity
Returns usage metrics for tables — how often they've been queried in the past 30 days.
When it's used: To prioritize commonly-used tables when multiple candidates match a search. Popular tables are more likely to contain the data the user is looking for.
Returns: Table names with query counts.
Tool Routing by Surface
Not all tools are available on every surface. The tool router selects the appropriate set:
| Tool | Chat | Slack | Dashboard | Query |
|---|---|---|---|---|
| search_tables | Yes | Yes | Yes | Yes |
| search_dashboards | Yes | Yes | Yes | Yes |
| describe_table | Yes | Yes | Yes | Yes |
| execute_query | Yes | Yes | Yes | Yes |
| list_connectors | Yes | Yes | Yes | Yes |
| query_popularity | Yes | Yes | Yes | Yes |
The dashboard surface may include additional layout and cell-editing tools specific to dashboard creation.
How the Agent Chooses Tools
The agent follows a general pattern:
- Understand the question — Parse what data is needed
- Search for existing dashboards — Call
search_dashboardsto check if an existing dashboard already answers the question. If a match is found, reference it directly - Search for tables — Call
search_tableswith relevant keywords - Inspect tables — Call
describe_tableon promising candidates - Write and execute SQL — Call
execute_querywith the generated query - Iterate if needed — If results don't answer the question, refine and re-query
The agent may skip steps if it already has enough context from previous messages in the conversation (e.g., it already knows which table to query from an earlier question).