HubSpot
Give agents read access to your HubSpot CRM — contacts, companies, deals, meetings, engagements, and forms — plus a send-email tool that delivers through Gmail and logs the message back to the contact's HubSpot timeline.
Every tool on this page requires a HubSpot connector (see
Connectors); pass its ID as connectorId. The
search tools all use HubSpot's CRM Search API: query is a free-text search,
the optional filters are combined with AND, results are paginated with
limit and the after cursor from the previous response, and properties
lets you request extra CRM properties beyond the defaults.
Search contacts TOOLHUBSPOT_SEARCH_CONTACTS
Searches contacts by free-text query — names, email addresses, and other
indexed properties all match. Narrow the results with lifecycleStage,
leadStatus, or a startDate/endDate window on the contact's create date.
This is the usual first step when an agent only has a name or email and needs
the HubSpot contact ID for the other tools.
Example
{
"toolType": "HUBSPOT_SEARCH_CONTACTS",
"connectorId": "V1StGXR8Z5",
"query": "@@{CUSTOMER_EMAIL}",
"lifecycleStage": "customer",
"limit": 20
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
query- Type
- string
- Description
- Free-text search query
- Name
lifecycleStage- Type
- string · optional
- Description
- Optional filter: subscriber, lead, marketingqualifiedlead, salesqualifiedlead, opportunity, customer, evangelist, other
- Name
leadStatus- Type
- string · optional
- Description
- Optional filter: e.g. NEW, OPEN, IN_PROGRESS, etc.
- Name
startDate- Type
- string · optional
- Description
- Optional: YYYY-MM-DD format, filters on createdate
- Name
endDate- Type
- string · optional
- Description
- Optional: YYYY-MM-DD format, filters on createdate
- Name
properties- Type
- string · optional
- Description
- Optional: comma-separated property names to return
- Name
limit- Type
- integer · optional
- Description
- Optional: max results (default 20, max 100)
- Name
after- Type
- string · optional
- Description
- Optional: pagination cursor from previous response
Get a contact TOOLHUBSPOT_GET_CONTACT
Fetches a single contact by its HubSpot contact ID, returning the default
property set plus anything you list in properties. Set associations to
pull the IDs of related records — for example "companies,deals" — so the
agent can chase the rest of the relationship graph.
Example
{
"toolType": "HUBSPOT_GET_CONTACT",
"connectorId": "V1StGXR8Z5",
"contactId": "@@{HUBSPOT_CONTACT_ID}",
"properties": "email,firstname,lastname,phone,lifecyclestage",
"associations": "companies,deals"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
contactId- Type
- string
- Description
- HubSpot contact ID (required)
- Name
properties- Type
- string · optional
- Description
- Optional: comma-separated property names
- Name
associations- Type
- string · optional
- Description
- Optional: comma-separated e.g. "companies,deals"
Search companies TOOLHUBSPOT_SEARCH_COMPANIES
Searches companies by free-text query, with optional filters on industry
and a create-date window. Returns matching company records with their IDs,
ready to feed into HUBSPOT_GET_COMPANY for full detail.
Example
{
"toolType": "HUBSPOT_SEARCH_COMPANIES",
"connectorId": "V1StGXR8Z5",
"query": "@@{COMPANY_NAME}",
"industry": "COMPUTER_SOFTWARE",
"limit": 20
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
query- Type
- string
- Description
- Free-text search query
- Name
industry- Type
- string · optional
- Description
- Optional filter: industry name
- Name
startDate- Type
- string · optional
- Description
- Optional: YYYY-MM-DD format, filters on createdate
- Name
endDate- Type
- string · optional
- Description
- Optional: YYYY-MM-DD format, filters on createdate
- Name
properties- Type
- string · optional
- Description
- Optional: comma-separated property names
- Name
limit- Type
- integer · optional
- Description
- Optional: max results (default 20, max 100)
- Name
after- Type
- string · optional
- Description
- Optional: pagination cursor
Get a company TOOLHUBSPOT_GET_COMPANY
Fetches a single company by its HubSpot company ID. Use properties for
extra fields and associations (e.g. "contacts,deals") to list the IDs of
people and deals attached to the company.
Example
{
"toolType": "HUBSPOT_GET_COMPANY",
"connectorId": "V1StGXR8Z5",
"companyId": "@@{HUBSPOT_COMPANY_ID}",
"properties": "name,domain,industry,numberofemployees",
"associations": "contacts,deals"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
companyId- Type
- string
- Description
- HubSpot company ID (required)
- Name
properties- Type
- string · optional
- Description
- Optional: comma-separated property names
- Name
associations- Type
- string · optional
- Description
- Optional: comma-separated e.g. "contacts,deals"
Search deals TOOLHUBSPOT_SEARCH_DEALS
Searches deals by free-text query with filters for pipeline, dealStage,
an amount range (minAmount/maxAmount), and a create-date window. Pipeline
and stage filters take HubSpot IDs, not display labels — run
HUBSPOT_GET_PIPELINES first to map labels to IDs.
Example
{
"toolType": "HUBSPOT_SEARCH_DEALS",
"connectorId": "V1StGXR8Z5",
"query": "@@{DEAL_KEYWORDS}",
"pipeline": "default",
"minAmount": "10000",
"startDate": "2026-01-01",
"limit": 20
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
query- Type
- string
- Description
- Free-text search query
- Name
pipeline- Type
- string · optional
- Description
- Optional filter: pipeline ID (e.g. "default")
- Name
dealStage- Type
- string · optional
- Description
- Optional filter: deal stage ID
- Name
minAmount- Type
- string · optional
- Description
- Optional filter: minimum deal amount
- Name
maxAmount- Type
- string · optional
- Description
- Optional filter: maximum deal amount
- Name
startDate- Type
- string · optional
- Description
- Optional: YYYY-MM-DD format, filters on createdate
- Name
endDate- Type
- string · optional
- Description
- Optional: YYYY-MM-DD format, filters on createdate
- Name
properties- Type
- string · optional
- Description
- Optional: comma-separated property names
- Name
limit- Type
- integer · optional
- Description
- Optional: max results (default 20, max 100)
- Name
after- Type
- string · optional
- Description
- Optional: pagination cursor
Get a deal TOOLHUBSPOT_GET_DEAL
Fetches a single deal by its HubSpot deal ID, with optional extra
properties and associations (e.g. "contacts,companies") so the agent
can see who and what the deal is attached to.
Example
{
"toolType": "HUBSPOT_GET_DEAL",
"connectorId": "V1StGXR8Z5",
"dealId": "@@{HUBSPOT_DEAL_ID}",
"properties": "dealname,amount,dealstage,closedate",
"associations": "contacts,companies"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
dealId- Type
- string
- Description
- HubSpot deal ID (required)
- Name
properties- Type
- string · optional
- Description
- Optional: comma-separated property names
- Name
associations- Type
- string · optional
- Description
- Optional: comma-separated e.g. "contacts,companies"
Get pipelines TOOLHUBSPOT_GET_PIPELINES
Lists every deal pipeline in the portal with its stages, including the stage
IDs that HUBSPOT_SEARCH_DEALS filters on. It takes no parameters beyond the
connector, so agents typically call it once to learn the portal's sales
process before filtering or interpreting deal stages.
Example
{
"toolType": "HUBSPOT_GET_PIPELINES",
"connectorId": "V1StGXR8Z5"
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
Search meetings TOOLHUBSPOT_SEARCH_MEETINGS
Searches meeting engagements, filtered by a startDate/endDate window on
the meeting start time and an optional outcome (SCHEDULED, COMPLETED,
RESCHEDULED, NO_SHOW, CANCELLED). Results come back sorted by meeting start
time and simplified to title, start/end time, outcome, and location — useful
for "what's on the calendar this week" style questions.
Example
{
"toolType": "HUBSPOT_SEARCH_MEETINGS",
"connectorId": "V1StGXR8Z5",
"startDate": "@@{WEEK_START}",
"endDate": "@@{WEEK_END}",
"outcome": "SCHEDULED",
"limit": 20
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
startDate- Type
- string · optional
- Description
- Optional: YYYY-MM-DD format, filters on hs_meeting_start_time
- Name
endDate- Type
- string · optional
- Description
- Optional: YYYY-MM-DD format, filters on hs_meeting_start_time
- Name
outcome- Type
- string · optional
- Description
- Optional filter: SCHEDULED, COMPLETED, RESCHEDULED, NO_SHOW, CANCELLED
- Name
properties- Type
- string · optional
- Description
- Optional: comma-separated property names
- Name
limit- Type
- integer · optional
- Description
- Optional: max results (default 20, max 100)
- Name
after- Type
- string · optional
- Description
- Optional: pagination cursor
Search engagements TOOLHUBSPOT_SEARCH_ENGAGEMENTS
Searches CRM activity records of one engagementType — calls, emails,
notes, or tasks — optionally windowed by startDate/endDate on the
engagement timestamp. This is the generalist companion to
HUBSPOT_SEARCH_MEETINGS: use it to reconstruct recent activity on an
account or audit what the sales team has logged.
Example
{
"toolType": "HUBSPOT_SEARCH_ENGAGEMENTS",
"connectorId": "V1StGXR8Z5",
"engagementType": "calls",
"startDate": "@@{REPORT_START_DATE}",
"limit": 50
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
engagementType- Type
- string
- Description
- Required: one of "calls", "emails", "notes", "tasks"
- Name
startDate- Type
- string · optional
- Description
- Optional: YYYY-MM-DD format, filters on hs_timestamp
- Name
endDate- Type
- string · optional
- Description
- Optional: YYYY-MM-DD format, filters on hs_timestamp
- Name
properties- Type
- string · optional
- Description
- Optional: comma-separated property names
- Name
limit- Type
- integer · optional
- Description
- Optional: max results (default 20, max 100)
- Name
after- Type
- string · optional
- Description
- Optional: pagination cursor
List forms TOOLHUBSPOT_LIST_FORMS
Lists the marketing forms in the portal with their names and GUIDs. Agents
run this to find the form GUID that HUBSPOT_GET_FORM_SUBMISSIONS needs.
Example
{
"toolType": "HUBSPOT_LIST_FORMS",
"connectorId": "V1StGXR8Z5",
"limit": 50
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
limit- Type
- integer · optional
- Description
- Optional: number of forms to return (default 20, max 100)
- Name
after- Type
- string · optional
- Description
- Optional: pagination cursor from previous response
Get form submissions TOOLHUBSPOT_GET_FORM_SUBMISSIONS
Fetches recent submissions for one form, identified by its GUID (from
HUBSPOT_LIST_FORMS). Each submission includes the submitted field values,
so an agent can triage new inbound leads or answer "who filled out the demo
request form today".
Example
{
"toolType": "HUBSPOT_GET_FORM_SUBMISSIONS",
"connectorId": "V1StGXR8Z5",
"formId": "@@{FORM_GUID}",
"limit": 20
}
connectorId in the tool configuration.Configuration fields
- Name
connectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
formId- Type
- string
- Description
- HubSpot form GUID (required)
- Name
limit- Type
- integer · optional
- Description
- Optional: number of submissions to return (default 20, max 50)
- Name
after- Type
- string · optional
- Description
- Optional: pagination cursor
Send email to contact TOOLHUBSPOT_SEND_EMAIL
Sends an email to a HubSpot contact and logs it on their CRM timeline. It
takes two connectors: the recipient address is looked up from the HubSpot
contact (you pass contactId, never a raw email address), the message is
sent from the connected Gmail account, and the sent email is then recorded
in HubSpot as an email engagement associated with the contact. At least one
of body (plain text) or bodyHtml is required. If the HubSpot logging
step fails, the email has still been sent — the response carries a
hubspotWarning instead of failing the whole call.
Example
{
"toolType": "HUBSPOT_SEND_EMAIL",
"hubspotConnectorId": "V1StGXR8Z5",
"gmailConnectorId": "aB3dE5fG7h",
"contactId": "@@{HUBSPOT_CONTACT_ID}",
"subject": "Following up on your demo request",
"body": "@@{EMAIL_BODY}",
"cc": "sales@example.com"
}
hubspotConnectorId and gmailConnectorId in the tool configuration.Configuration fields
- Name
hubspotConnectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
gmailConnectorId- Type
- string (ID)
- Description
- Required string (ID) value. References a connector by ID.
- Name
contactId- Type
- string
- Description
- HubSpot contact ID — recipient email is fetched from HubSpot
- Name
subject- Type
- string
- Description
- Required string value.
- Name
body- Type
- string
- Description
- Required string value.
- Name
bodyHtml- Type
- string · optional
- Description
- Optional
- Name
cc- Type
- string · optional
- Description
- Optional
- Name
bcc- Type
- string · optional
- Description
- Optional