How to build a Custom Database tool
A Custom Database Tool is a custom tool that runs a SQL query against a database you connect. The AI agent calls the tool with the values it needs — an account number, an order ID, a status — and the tool returns the matching rows. Use it when the answer a workflow needs already lives in your own database and you want the agent to read it directly, without exporting the data or copying it into a spreadsheet.
A Custom Database tool is a good fit when the lookup is a query over structured tables — a customer record by ID, open orders for an account, a price by SKU. If the task instead needs judgment over unstructured text, use a Custom AI Tool; if it is a fixed rule or calculation, use a Custom Code Tool; if the reference data lives in a spreadsheet rather than a database, use a Spreadsheet Lookup Tool. Those alternatives are covered in Custom Tools and How to build a Spreadsheet Lookup tool.
Before you start
The tool runs its query through a SQL Database connection, so add that connection first:
In Account → Connections, add a connection of type SQL Database. Choose your database type (PostgreSQL, MySQL, Microsoft SQL Server, Oracle, and others), then enter the host, port, database name, and the user and password the tool should connect with.
Make sure the connection is available to the thunk. Connecting business data through a SQL database is described in Connect business applications.
Connect with a database account that has only the access the workflow needs — typically read access to the tables the tool queries.
Create the tool
In the thunk's Custom-built tools, open Add New Tool and choose Custom Database Tool.
A Create new database tool dialog opens with an Intent field. Describe what the tool should look up or read — for example, "Find the account record for a given account number" or "Return the open orders for a customer ID." The builder uses this to draft the SQL and the tool's inputs.
Save the tool. The builder then designs the query and inputs from your intent; this runs in the background, and you can watch its progress from the tool's detail view.
Review the tool
Open the tool from the tools list to review what the builder produced. A Custom Database tool has the same core sections as every custom tool:
Definition — the
snake_casetool name and the description the AI agent reads to decide when to call the tool. The same naming guidance applies as for every custom tool; see the style guide in Custom Tools.Inputs — the named values the agent passes on each call, such as the lookup key. Each input has a description and a type; a precise description helps the agent supply the right value.
SQL Command — the query the tool runs. Placeholders in the command stand in for the tool's inputs, so the values the agent passes are bound into the query safely rather than pasted into the SQL text. Review the command and adjust it if the query needs to be more specific than the intent produced.
Connections — the SQL database the tool queries. Choose the SQL Database connection you created (or add one from here if you have not yet). A Custom Database tool uses exactly one database connection.
How the AI agent calls the tool
At run time the agent reads the tool's description and inputs, fills in the inputs from the work item's data, and calls the tool. The tool runs the SQL command with those values and returns the rows that matched. The agent then uses those rows in the workflow — reading a field, comparing values, or updating the work item.
Because you decide the query and which inputs the agent can pass, the tool only reaches the tables and columns your command names; the agent cannot run arbitrary SQL.
Trying it out
Like every custom tool, a Custom Database tool has a Try it! action so you can run it with test input values and confirm it returns the rows you expect before the workflow relies on it. Run it once against a known record to check both the query and the connection before deploying.