Teaching an AI agent to operate HubSpot

The problem

A marketing-ops team's recurring work is building workflows: enroll this segment, wait, send this email, branch on behavior, mark them converted. In HubSpot that's a point-and-click job: slow, manual, and exactly the sort of structured, schema-heavy task an AI agent should be able to take on.

The question wasn't whether you can call the HubSpot API from code. It was what would make these operations safe to hand to a model that acts on its own. That turned out to be the entire engineering problem.

The product case

The problem owner was the marketing team: lifecycle workflows, audience segments, and campaign infrastructure are recurring, schema-heavy work, and all of it queued behind the ops seat. The recurring cost was easy to size (it showed up every week), and the blast radius of getting it wrong (a workflow that silently enrolls nobody, or the wrong ten thousand people) is what kept it manual.

Alternatives I rejected:

• Keep it point-and-click. Safe, but it scales the queue, not the team: every new campaign still buys a slot behind the same seat.
• One-off scripts and RPA. Fast for any single job, brittle for the portfolio of them. With no verification story, failures stay silent.
• A thin API wrapper for the agent. The obvious build, and the dangerous one: it hands a model the ability to mutate a system of record while trusting 200 OK. The trap below is why that's not a product.

The bet was that the trust layer was the product: make each operation safe enough to run unattended and the agent absorbs the recurring work, not just one task. Scope followed the same logic: workflows first (the recurring job), lists second (they validate the filters workflows can't), CRM reads third (they size audiences before anything sends). Each domain shipped with the reads an agent needs to verify its own writes.

Success was measured in work absorbed: the operators ran in production automating campaign creation and system administration for the marketing team, saving six figures a year in ops cost. The pattern proved portable enough to extend to two more systems of record.

The core idea: verify-after-write

Every tool, read or write, returns one envelope shape. The part that matters is the audit block, and specifically audit.verified:

{
  "ok": true,
  "operation": "workflows.set_enrollment_criteria",
  "data": { /* request echo + the re-fetched object */ },
  "audit": {
    "attempted": true,
    "verified": true,        // re-read the object and confirmed the change
    "targetId": "1234567890",
    "targetName": "Trial → Activation Nurture"
  }
}

A write tool performs its mutation and then re-fetches the object to confirm the change actually landed before reporting success. Creates read the new record back; deletes re-list to confirm the object is gone; list-membership writes re-read each record's memberships. The agent branches on audit.verified, never on a bare HTTP status. This single convention is what makes the tools trustworthy enough to run unattended.

Four more decisions that made it safe

What it looks like in use

One prompt ("enroll un-activated trial contacts into a 3-step nurture and mark them converted when they activate") becomes a sequence of verifiable tool calls:

# size the audience before building anything
crm.search        { objectType:"contacts", count:true, filterGroups:[…] }   → total: 4,812
# build the flow incrementally, each step verified
workflows.create_manual          { name:"Trial → Activation Nurture" }      → verified
workflows.set_enrollment_criteria{ workflowId, enrollmentCriteria:[…] }     → verified
workflows.set_actions            { workflowId, actions:[email,delay,email…] }→ verified
workflows.set_goal_criteria      { workflowId, goalFilterBranch:[…] }       → verified
workflows.set_enabled            { workflowId, isEnabled:true }             → verified

Because each step is re-read from HubSpot, the agent can detect the "always false" trap before turning the workflow on, the failure mode that's otherwise invisible until a campaign sends to nobody.

The tool surface

24 tools across three domains, every one returning the same envelope. Coverage isn't the point: each domain ships the reads an agent needs to verify its own writes.

How it's put together

Every HubSpot request flows through a single fetch choke point with typed errors, every tool renders the same envelope, and the sanitizers that make read-modify-write safe live in one place. Small enough to audit in a sitting:

src/
  server.ts     MCP bootstrap: registers all 24 tools, one envelope renderer
  hubspot.ts    the single fetch choke point + typed HubSpotApiError
  config.ts     .env loading + requireEnv
  types.ts      ToolEnvelope / ToolAudit, the shared contract
  utils.ts      envelopes, exact-match targeting, read-modify-write sanitizers
  workflows.ts  the 11 flow tools (the centerpiece)
  lists.ts      the 9 list tools, incl. per-record membership verification
  crm.ts        the 4 CRM tools, incl. count-mode search

The most useful thing I learned

That insight only comes from running the thing in production and watching a "successful" workflow enroll zero contacts. That is the difference between a wrapper and an operator.

An operator pattern, not a one-off

HubSpot was the first system, not the last. The same contract (verify-after-write auditing, exact-match targeting, honest failure signals) now runs against two more systems of record in the GTM stack, both in production:

Three systems in, the pattern holds: the API wrapper is the easy 20%. The trust layer is the product.

At a glance

• Workflows: create, set enrollment / actions / goal, clone, enable, delete, cross-workflow jumps
• Lists: dynamic & manual lists, in-place filter edits, per-record membership verification
• CRM: structured filterGroups search, count-only mode, verified property writes

Takeaway

The interesting work in agent tooling is the trust layer: verification, unambiguous targeting, honest failure signals, and encapsulating the API's sharp edges so a model can't fall on them. Build those in and an agent can do real, consequential work in a system of record without a human double-checking every step.