> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent tools

> Use HubSpot agent tools in Ravenna rules to search contacts, look up companies, retrieve deals, and surface CRM data during ticket conversations.

HubSpot provides AI agent tools for CRM data retrieval and deal tracking. Reference these tools in agent rules (Natural language instructions defining agent behavior) using @ mentions to enable automated customer account lookups and deal status checks.

***

## Look up customers

> [accordion] 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 Contacts`
>
> **Input 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.
>
> 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.

> [accordion] Search companies
>
> 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 Companies`
>
> **Input 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.
>
> 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

> [accordion] Search 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 Deals`
>
> **Input 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.
>
> 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.

> [accordion] List deals
>
> 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 Deals`
>
> **Input 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.
>
> 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.

> [accordion] Get deal details
>
> 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 Details`
>
> **Input 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.
>
> 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.

> [accordion] List owners
>
> 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 Owners`
>
> **Input 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.
>
> 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](https://docs.ravenna.ai/documentation/automate/agents/configure.md#tool-execution-policies).

***

## Setup

**1. Install HubSpot integration**

Follow the [HubSpot setup guide](https://docs.ravenna.ai/integrations/hubspot/setup.md) 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 rules (Natural language instructions defining agent behavior) 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](https://docs.ravenna.ai/documentation/automate/agents/configure.md) and writing effective rules


## Related topics

- [Agent tools](https://docs.ravenna.ai/integrations/fleet/agent-tools.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.