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.
Check first whether the database has its own MCP server (Snowflake and Databricks, among others, offer one) or a REST API. If it does, connect that instead: its tools work like any other connection's tools, and the database's own permissions decide what they can do. Use a Custom Database tool when the database offers neither. See Connecting to External Systems and Tools.
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. Under Intent, 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. Tool name and Description are optional: leave them blank and the builder fills them in. If you set them, use a clear
snake_casename and a description that says what the tool returns — the AI agent reads both to decide when to call it. See the style guide in Custom Tools.Select Create tool. The tool's page opens with the Tool Builder AI working in the chat beside it: from your intent it writes the SQL command and the tool's inputs. Check what it set, and change it, as described below.
Review the tool
Review what the builder produced on the tool's page (or open the tool later from Custom-built tools). The Definition tab holds the tool's name and description; the Implementation tab holds what the tool takes and how it runs the query:
Tool name and Description (Definition tab) — 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 (Implementation tab) — 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.
Connections (Implementation tab, Details) — the SQL database the tool queries. Choose the SQL Database connection you created. If you have not created it yet, choose + Create new connection in the list; it opens Account Connections in a new tab. A Custom Database tool uses exactly one database connection.
SQL Command (Implementation tab, Details) — 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.
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 tab 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.
