> ## 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 customer information lookup. Reference these tools in <Tooltip headline="Agent rules" tip="Natural language instructions defining agent behavior" cta="Learn about agent rules" href="/documentation/automate/agents/configure#rules">agent rules</Tooltip> using @ mentions to enable automated customer account lookups and deal tracking.

***

## Available tools

<AccordionGroup>
  <Accordion title="Search contacts" defaultOpen>
    Searches for contacts in HubSpot by email address, name, or other criteria. Returns contact details including email, name, company, and associated properties.

    **Tool name:** `@Search contacts with HubSpot`

    **Common use cases:**

    * Look up customer information by email
    * Verify contact existence before creating tickets
    * Retrieve customer details for support requests
    * Find contact IDs for other operations

    **Example rule:**

    <Prompt description="HubSpot contact lookup rule">
      When a user asks about a customer account, use @Search contacts
      with HubSpot to find the contact by email. Provide the customer's
      name, company, and account status to the user.
    </Prompt>
  </Accordion>

  <Accordion title="Search companies">
    Searches for companies in HubSpot by domain, name, or other criteria. Returns company details including name, domain, industry, and associated properties.

    **Tool name:** `@Search companies with HubSpot`

    **Common use cases:**

    * Look up company information
    * Verify company existence
    * Retrieve company details for account management
    * Find company IDs for deal lookups

    **Example rule:**

    <Prompt description="HubSpot company lookup rule">
      When a user asks about a company account, use @Search companies
      with HubSpot to find the company by domain. Summarize the company
      details and recent activity.
    </Prompt>
  </Accordion>

  <Accordion title="Search deals">
    Searches for deals in HubSpot by deal name, stage, or other criteria. Returns deal details including amount, stage, close date, and associated contacts.

    **Tool name:** `@Search deals with HubSpot`

    **Common use cases:**

    * Look up deal status
    * Track sales pipeline
    * Retrieve deal details for account reviews
    * Find deals by customer or stage

    **Example rule:**

    <Prompt description="HubSpot deal search rule">
      When a user asks about deal status, use @Search deals with HubSpot
      to find active deals for the customer. Provide a summary of deal
      stages, amounts, and expected close dates.
    </Prompt>
  </Accordion>

  <Accordion title="List deals">
    Retrieves a list of deals from HubSpot with optional filtering by stage, owner, or date. Returns paginated deal information for analysis and reporting.

    **Tool name:** `@List deals with HubSpot`

    **Common use cases:**

    * Review active deals pipeline
    * Generate deal reports
    * Track deals by owner or stage
    * Monitor sales activity

    **Example rule:**

    <Prompt description="HubSpot pipeline overview rule">
      When a user asks for a pipeline overview, use @List deals with
      HubSpot to retrieve active deals. Group by stage and provide a
      summary of total value and count per stage.
    </Prompt>
  </Accordion>

  <Accordion title="Get deal">
    Retrieves detailed information about a specific deal by ID. Returns complete deal properties, associated contacts, companies, and timeline.

    **Tool name:** `@Get deal with HubSpot`

    **Common use cases:**

    * Get complete deal details
    * Review deal history
    * Check deal associations
    * Analyze deal properties

    **Example rule:**

    <Prompt description="HubSpot deal details rule">
      When a user provides a deal ID, use @Get deal with HubSpot to
      retrieve the complete deal information. Provide a detailed summary
      including stage, amount, contacts, and recent activity.
    </Prompt>
  </Accordion>

  <Accordion title="List owners">
    Retrieves the list of HubSpot users who can own contacts, companies, or deals. Returns owner names and IDs for assignment and filtering operations.

    **Tool name:** `@List owners with HubSpot`

    **Common use cases:**

    * Find owner information for deal assignment
    * Reference owners in queries
    * Build owner-specific reports
    * Validate owner assignments
  </Accordion>
</AccordionGroup>

***

## Setup

<Steps>
  <Step title="Install HubSpot integration">
    Follow the [HubSpot setup guide](/integrations/hubspot/setup) to connect your HubSpot account to Ravenna.
  </Step>

  <Step title="Configure agent">
    Navigate to your agent's settings and ensure HubSpot tools appear in the Tools section under Capabilities.
  </Step>

  <Step title="Create rules">
    Write <Tooltip headline="Agent rules" tip="Natural language instructions defining agent behavior" cta="Learn about agent rules" href="/documentation/automate/agents/configure#rules">rules</Tooltip> that reference HubSpot tools using @ mentions.
  </Step>

  <Step title="Test tools">
    Test your rules in a controlled environment to verify tools work as expected.
  </Step>
</Steps>

***

## Best practices

* Combine contact, company, and deal searches for comprehensive customer lookups
* Use search tools before attempting to get specific records by ID
* Consider pagination when listing large numbers of deals
* Provide context about what the user asked for when presenting results
* Format CRM data clearly for easy comprehension

<Callout icon="link" color="#6B7280">
  Learn more about [configuring agents](/documentation/automate/agents/configure) and writing effective rules
</Callout>