---
title: How We Built a HubSpot Breeze Agent Tool That Answers From HubDB
description: "How we built HubDB Lookup, a Breeze agent tool that lets HubSpot agents answer from HubDB tables: how agent tools work, the HubDB filter gotchas, and test results."
---

[PixTheme](https://www.pixtheme.com/blog)

# [How We Built a HubSpot Breeze Agent Tool That Answers From HubDB](https://www.pixtheme.com/blog/how-we-built-a-hubspot-breeze-agent-tool-that-answers-from-hubdb)

 Written by [Rafayel Sh.](https://www.pixtheme.com/blog/author/rafayel-sh) | Fri, Oct 30, '26

Breeze agents in HubSpot only know what their tools let them see. A lot of useful business data lives in **HubDB**: store locations, product specs, event schedules, team members, property listings. So we built **HubDB Lookup**, a pair of agent tools that let any Breeze agent find the right HubDB table and search it. No setup per table.

This post explains how HubSpot agent tools work, how ours is built, and the five things that tripped us up. If you just want to try it, it's [free during early access](https://assets.pixtheme.com/apps/hubdb-lookup).

## What a Breeze agent tool is

An agent tool is a **custom workflow action with extra settings for AI**. You build it in a HubSpot developer project (platform version 2026.03), and in its configuration you add `AGENTS` as a supported client next to `WORKFLOWS`. Two settings matter most:

- **Tool type.** `GET_DATA` for tools that read information, like ours.
- **The description for the AI** (`llmConfig.actionDescription`). The agent reads it to decide when to call the tool and how to fill its inputs. It's effectively a prompt, and it matters more than any other line in the project.

When an agent decides to use the tool, HubSpot sends a signed POST request to your `actionUrl` with the account ID and the inputs. Your endpoint answers with output fields, which the agent reads. Agent tools can't use HubSpot serverless functions, so the endpoint has to be your own public HTTPS service. Agent tools are still in beta, so you need a developer account that's opted in, and a test account to try them.

## Why HubDB is a good fit for agents

HubDB tables are structured: named columns, types, select options. That's exactly what an AI agent needs to filter reliably instead of guessing. And many HubSpot sites already keep their most-asked-about facts in HubDB because those tables power dynamic pages. Opening that data to agents means a support or sales agent can answer "Which stores are open on Saturday?" from the same rows that render the store pages.

We kept the tool general on purpose. It doesn't know about stores or listings. It describes whatever tables an account has, and the agent works out the rest.

## How HubDB Lookup works

The app has two tools:

1. **List HubDB tables** returns every published table with its columns, column types and the options of select columns.
2. **Search HubDB table** takes a table, filters written one per line (`city = Austin`, `price <= 500`, `beds >= 3`), the columns to return, a sort and a row limit, and returns the matching rows as readable text.

Behind them is a small Cloudflare Worker. It checks HubSpot's request signature, looks up the account's OAuth token, turns the filters into HubDB API queries, and formats the rows: select labels instead of IDs, yes/no for checkboxes, dates as `YYYY-MM-DD`, rich text without HTML. The app only asks for read access to HubDB tables and rows, and it doesn't store any table data.

## 5 things we learned building it

### 1. Every output value must be a string

Output fields are typed as strings, so we return numbers like the row count as strings too, and build every response through one helper that stringifies each value. The response shape is simple:

```
{
  "outputFields": {
    "rows": "1. Austin Downtown\n   city: Austin\n   saturday_hours: 9:00–18:00",
    "row_count": "1",
    "total_matches": "1",
    "hs_execution_state": "SUCCESS"
  }
}
```

For errors we return `FAIL_CONTINUE` with a plain-language `error` output, such as "Unknown column "colour". Use List HubDB tables to see the columns." The agent reads it and usually fixes its own call on the next try.

### 2. Verify the signature, and log why it fails

HubSpot signs each request. The v3 signature is an HMAC-SHA256 of the method, URL, body and timestamp, keyed with your app's client secret and base64-encoded. Reject requests older than five minutes. HubSpot also sends the older v2 signature, so we accept either. Our first test failed every signature because the client ID had been saved as the secret. Logging which check failed, without logging secrets, found that in one look.

### 3. HubDB filters have quirks the docs don't spell out

We tested each filter against the live API before trusting it:

- **Select columns** filter by the option's *name*, not its label. Agents write labels ("For sale"), so we map labels to names.
- **Multi-select columns:** `eq` means "exactly this set of options". To find rows that *have* an option, use `contains`.
- **Empty text** is stored as an empty string, so `is_null` finds nothing. Filter on `= ''` instead.
- **`in` doesn't work on text columns.** We return a clear error telling the agent to search once per value.
- **Dates** filter as epoch milliseconds. ISO dates are rejected.

### 4. Agents search by topic, not by table name

When we asked for "the most expensive homes for sale", the agent first asked the table list for "homes", then "listings". Our table was called "Openhouse properties", so both came back empty. The agent recovered, but now a search with no match returns every table with a short note. Design tool outputs so a reasonable guess still gets a useful answer.

### 5. Expect setup quirks while agent tools are in beta

- A developer test account created in the UI may not include Content Hub, which means no HubDB. Creating it with `hs test-account create` at Enterprise tiers fixed that.
- If you uninstall and reinstall the app, agents still point to the old tools and fail with "The agent configuration references actions that no longer exist". Remove the tools and add them again.
- Before anyone outside your test accounts can install the app, sign the app's Acceptable Use Policy on its Distribution tab.

## Real answers from our tests

We tested with the Developer Tool Testing Agent in an account with three tables: store locations, property listings and real estate agents. All four questions were answered correctly against the data:

- **"Which of our stores are open on Saturday, and what are their hours?"** All 4 correct stores with their hours.
- **"Do we have a store with a café in Dallas?"** A correct "no". It searched, got nothing, then listed both Dallas stores to double-check.
- **"Show me the 3 most expensive homes for sale with at least 3 bedrooms."** The right 3 of 5 matches, sorted by price.
- **"Who is the agent for the Garden cottage, and what's their phone number?"** It found the listing's agent in one table and her phone number in another.

## Frequently asked questions

### What do I need to use HubDB Lookup?

A HubSpot account with HubDB (Content Hub Professional or Enterprise), Breeze agents, and at least one published HubDB table.

### Can the tool change my tables or see my contacts?

No. It only has read access to HubDB tables and rows. It can't edit HubDB or see contacts, deals or any other HubSpot data.

### Can I use the tools in workflows too?

Yes. Both tools are workflow actions, so you can use the matching rows in emails, property updates or branches.

### Is it on the HubSpot Marketplace?

Not yet. It's in early access while we work with the first users, and we plan to list it once it's proven in real accounts.

## Try it free

HubDB Lookup is **free during early access**, and we'll help you set it up on a short call: connect it, check your tables and test your agent with you. [Get HubDB Lookup](https://assets.pixtheme.com/apps/hubdb-lookup) or read the [documentation](https://docs.pixtheme.com/hubdb-lookup/).

Want an agent tool built for your own data or system? We build [custom HubSpot modules and integrations](https://www.pixtheme.com/services/hubspot-custom-modules), and you can [hire a HubSpot developer](https://www.pixtheme.com/hire-hubspot-developer) from our team.

[View full post](https://www.pixtheme.com/blog/how-we-built-a-hubspot-breeze-agent-tool-that-answers-from-hubdb)

```json
{
  "@context" : "http://schema.org",
  "@type" : "BlogPosting",
  "author" : {
    "@type" : "Person",
    "name" : "Rafayel Sh."
  },
  "dateModified" : "2026-10-30T20:11:14.860Z",
  "datePublished" : "2026-10-30T20:11:14Z",
  "headline" : "How We Built a HubSpot Breeze Agent Tool That Answers From HubDB",
  "image" : {
    "@type" : "ImageObject",
    "height" : 60,
    "url" : "/hs/hsstatic/content_shared_assets/static-1.4092/img/default-amp-logo.png",
    "width" : 60
  },
  "mainEntityOfPage" : "https://www.pixtheme.com/blog/how-we-built-a-hubspot-breeze-agent-tool-that-answers-from-hubdb",
  "publisher" : {
    "@type" : "Organization",
    "logo" : {
      "@type" : "ImageObject",
      "height" : 60,
      "url" : "/hs/hsstatic/content_shared_assets/static-1.4092/img/default-amp-logo.png",
      "width" : 60
    },
    "name" : "HubSpot Development Blog"
  }
}
```