Create your first tool

Tools are the queries and actions you expose to AI agents. Each tool has a fixed SQL template, typed parameters, and a description that helps AI agents decide when to call it.

Anatomy of a tool

Creating a tool

1. Go to Tools and click Create tool
2. Fill in the name and description
3. Select a source
4. Write your SQL template
5. Define parameters
6. Test and save

Writing SQL templates

Templates use {{ parameter }} syntax for value substitution and Jinja2 conditionals for optional clauses.

Basic template

SELECT product_name, revenue
FROM sales
WHERE region = {{ region }}
ORDER BY revenue DESC
LIMIT {{ limit }}

With optional parameters

Use {% if param %} blocks for optional filters:

SELECT customer_name, total_spent, last_order_date
FROM customers
WHERE 1=1
{% if region %}
  AND region = {{ region }}
{% endif %}
{% if min_spend %}
  AND total_spent >= {{ min_spend }}
{% endif %}
ORDER BY total_spent DESC
LIMIT {{ limit }}

When region is not provided, the clause is omitted entirely — no partial SQL, no errors.

Aggregation example

SELECT
  DATE_TRUNC('month', order_date) AS month,
  COUNT(*) AS order_count,
  SUM(amount) AS total_revenue
FROM orders
WHERE order_date >= {{ start_date }}
  AND order_date < {{ end_date }}
GROUP BY month
ORDER BY month

Defining parameters

Each parameter has:

Testing tools

Click Test to execute the tool with sample parameter values. The test runs against your actual database and returns real results.

The test result shows:

• Data — query results as a table
• Row count — number of rows returned
• Execution time — how long the query took

SQL validation

Before saving, Datatape validates your SQL template:

• Read-only check — SQLGlot parses the SQL and rejects INSERT, UPDATE, DELETE, DROP
• Template rendering — Verifies {{ parameters }} and {% if %} blocks render correctly
• Parameter binding — Confirms all parameters in the template are defined

You can also validate SQL independently via the Validate SQL button without saving the tool.

Previewing execution

Click Preview to see the rendered SQL without executing it. This shows exactly what query would run with your test parameters — useful for debugging complex templates.

-- Rendered SQL (preview)
SELECT customer_name, total_spent, last_order_date
FROM customers
WHERE 1=1
  AND region = $1
  AND total_spent >= $2
ORDER BY total_spent DESC
LIMIT $3

-- Parameters: ['us-west', 1000, 25]

Best practices

• Write descriptive tool names — get_revenue_by_quarter is better than query1
• Write clear descriptions — AI agents use the description to decide when to call the tool. Be specific about what it returns and when to use it.
• Use optional parameters — Let AI agents call tools with minimal inputs. Use {% if %} blocks for optional filters.
• Set sensible defaults — Default limit to 10 or 25 to prevent large result sets.
• Add parameter descriptions — Help AI agents understand what values to pass (e.g., "ISO country code like 'US' or 'GB'").