Skip to main content
HubSpot provides AI agent tools for CRM data retrieval and deal tracking. Reference these tools in using @ mentions to enable automated customer account lookups and deal status checks.

​
Look up customers

Search contacts

Searches HubSpot contacts using flexible filter criteria. Filters within a group combine with AND logic; multiple groups combine with OR logic. Use the IN operator to search multiple values in a single call.Tool name: @Search HubSpot ContactsInput fields:
  • filter_groups (required) - an array of filter groups. Each group contains one or more filters, each with a property_name (for example email, firstname, company, or lifecyclestage), an operator (EQ, NEQ, CONTAINS_TOKEN, IN, NOT_IN, BETWEEN, HAS_PROPERTY, GT, GTE, LT, LTE), and a value string or values array for IN/NOT_IN.
  • properties (optional) - HubSpot properties to return. Defaults to firstname, lastname, and email.
  • sorts (optional) - sort order, each with a property_name and direction (ASCENDING or DESCENDING).
  • limit (optional) - results per page, default 10, max 100.
  • after (optional) - pagination cursor from a previous response.
Output data:
  • contacts - each with id, email, firstName, lastName, fullName, and hubspot_url.
  • total - total number of contacts matching the filters in HubSpot.
  • returned - number of contacts in this response.
  • paging - contains paging.next.after cursor when more results are available.
Common use cases:
  • Look up a customer by email address before responding to a support request
  • Find contacts at a specific company using the company property
  • Search for all contacts with a given lifecycle stage
  • Batch-search multiple email addresses in a single call with the IN operator
Example rule:

When a user asks about a customer account, use @Search HubSpot Contacts to find the contact by email address. Reply with the customer's name, company, and any other relevant details. If no contact is found, let the user know.

Searches HubSpot companies using flexible filter criteria. Filters within a group combine with AND logic; multiple groups combine with OR logic. Use the IN operator to search multiple domains or names in a single call.Tool name: @Search HubSpot CompaniesInput fields:
  • filter_groups (required) - an array of filter groups. Each group contains one or more filters, each with a property_name (for example domain, name, industry, or city), an operator, and a value string or values array.
  • properties (optional) - HubSpot properties to return. Defaults to name and domain.
  • sorts (optional) - sort order, each with a property_name and direction.
  • limit (optional) - results per page, default 10, max 100.
  • after (optional) - pagination cursor from a previous response.
Output data:
  • companies - each with id, name, domain, and hubspot_url.
  • total - total number of companies matching the filters in HubSpot.
  • returned - number of companies in this response.
  • paging - contains paging.next.after cursor when more results are available.
Common use cases:
  • Look up a company by domain to find its associated deals
  • Search for companies in a specific industry or location
  • Find company IDs to use as filters in @Search HubSpot Deals
  • Batch-search multiple company domains in a single call
Example rule:

When a user asks about a company account, use @Search HubSpot Companies to find the company by domain. Summarize the company name, domain, and any additional properties requested.

​
Track deals

Searches HubSpot deals using flexible filter criteria. At least one filter group is required; use @List HubSpot Deals for unfiltered listing. Results automatically include associated company information; contact associations are opt-in.Tool name: @Search HubSpot DealsInput fields:
  • filter_groups (required) - an array of filter groups. Each group contains one or more filters, each with a property_name (for example dealstage, amount, hs_priority, hs_is_closed, closedate, associations.company, or hubspot_owner_id), an operator, and a value string or values array. To filter by company or owner, use @Search HubSpot Companies or @List HubSpot Owners first to get the ID.
  • sorts (optional) - sort order, each with a property_name and direction.
  • limit (optional) - results per page, default 20, max 100.
  • after (optional) - pagination cursor from a previous response.
  • include_contacts (optional) - when true, includes associated contacts on each deal. Adds two extra API calls.
Output data:
  • deals - each with id, name, amount, stage, pipeline, closeDate, priority, isClosed, isClosedWon, companies, primaryCompany, ownerId, and hubspot_url.
  • total - total number of deals matching the filters.
  • returned - number of deals in this response.
  • paging - contains paging.next.after cursor when more results are available.
Common use cases:
  • Find all open deals for a specific company by filtering on associations.company
  • List high-priority deals by filtering hs_priority to high
  • Filter deals by owner using an owner ID from @List HubSpot Owners
  • Search deals within a close date range using the BETWEEN operator
Example rule:

When a user asks about deal status for a customer, use @Search HubSpot Companies to get the company ID, then use @Search HubSpot Deals with an associations.company filter to find their deals. Summarize the deal stages, amounts, and expected close dates.

Returns recent deals from HubSpot without filtering, automatically including company associations. Use this when you need an overview of recent deals without specific filter criteria. For filtered searches, use @Search HubSpot Deals.Tool name: @List HubSpot DealsInput fields:
  • limit (optional) - maximum number of deals to return, default 50, max 100.
  • include_contacts (optional) - when true, includes associated contacts on each deal. Adds two extra API calls.
Output data:
  • deals - each with id, name, amount, stage, pipeline, closeDate, priority, isClosed, companies, primaryCompany, ownerId, and hubspot_url.
  • total - number of deals returned.
Common use cases:
  • Get an overview of recent deals for a pipeline review
  • List deals and group them by company
  • Show recent deal activity when no specific filter is needed
  • Pull deals for summarization or reporting
Example rule:

When a user asks for a pipeline overview, use @List HubSpot Deals to retrieve recent deals. Group results by company and provide a summary of deal stages and amounts.

Returns full details for a specific HubSpot deal by ID, including all deal properties and associated company information. Contact associations are opt-in.Tool name: @Get HubSpot Deal DetailsInput fields:
  • deal_id (required) - the ID of the HubSpot deal to retrieve.
  • include_companies (optional) - defaults to true; set to false to skip company lookup.
  • include_contacts (optional) - defaults to false; set to true to include associated contacts.
Output data:
  • deal - the full deal record including id, name, amount, stage, pipeline, closeDate, priority, forecastCategory, probability, isClosed, isClosedWon, arr, mrr, tcv, acv, companies, primaryCompany, ownerId, createdAt, updatedAt, and hubspot_url. Includes contacts when include_contacts is true.
Common use cases:
  • Pull complete deal details when a user provides a deal ID
  • Retrieve forecast data and health indicators for a deal review
  • Check associated companies and contacts for a specific deal
  • Look up revenue fields such as ARR or MRR
Example rule:

When a user provides a HubSpot deal ID, use @Get HubSpot Deal Details to retrieve the full record including companies. Summarize the deal name, stage, amount, close date, and associated company.

Returns the HubSpot users who can be assigned deals, contacts, or companies, along with their IDs, names, and email addresses. Use it to find an owner ID before filtering deals by owner in @Search HubSpot Deals.Tool name: @List HubSpot OwnersInput fields:
  • email (optional) - filter to a specific owner by email address.
  • limit (optional) - maximum number of owners to return, default 100, max 500.
Output data:
  • owners - each with id, email, firstName, lastName, and fullName.
  • total - total number of owners matching the filter.
  • returned - number of owners in this response.
Common use cases:
  • Find an owner ID by email before filtering deals with @Search HubSpot Deals
  • List all HubSpot owners to show who can be assigned deals
  • Confirm an owner’s ID before building a report filtered by owner
Example rule:

When a user asks for deals owned by a specific person, use @List HubSpot Owners with their email address to get the owner ID, then use @Search HubSpot Deals with a hubspot_owner_id filter to retrieve their deals.

A tool with no execution policy set runs without asking. When Copilot drafts a rule, it suggests Requires confirmation for write tools and Requires approval for delete tools, and you can change either per rule. See tool execution policies.

​
Setup

1

Install HubSpot integration

Follow the HubSpot setup guide to connect your HubSpot account to Ravenna.
2

Configure agent

Open your agent’s settings and add the HubSpot tools you want it to use under Tools. An admin has to attach each tool before an agent or rule can call it.
3

Create rules

Write that reference HubSpot tools using @ mentions.
4

Test tools

Test your rules on a real request to verify the tools work as expected.

​
Best practices

  • Chain lookups for deal filters. Use @Search HubSpot Contacts or @Search HubSpot Companies first to get IDs, then pass them as associations.contact or associations.company filters in @Search HubSpot Deals.
  • Use list for overviews, search for targeted queries. @List HubSpot Deals returns recent deals without filtering; @Search HubSpot Deals requires at least one filter group and is better for specific criteria.
  • Look up owners by email before filtering. Use @List HubSpot Owners with an email address to get the owner ID, then pass it as a hubspot_owner_id filter rather than searching by name.
  • Page through large result sets. When paging.next.after is present in a response, pass it as the after parameter with the same filters and limit to fetch the next page.
Learn more about configuring agents and writing effective rules
Last modified on September 29, 2026