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

# Use tools in Agent Studio

> Extend your agent's capabilities with built-in, client-side, and MCP tools.

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

export const Filter = () => <Tooltip tip="A filter is a condition that limits which records Algolia returns. Filters often use one or more facet-value pairs, such as brand:Apple AND color:red. You can also filter by numeric values, dates, tags, booleans, or geographic constraints." cta="Filtering" href="/doc/guides/managing-results/refine-results/faceting">
    filter
  </Tooltip>;

export const Facet = () => <Tooltip tip="An attribute in your records that lets users filter or group results (for example, by color, brand, or price)." cta="Faceting" href="/doc/guides/managing-results/refine-results/faceting">
    facet
  </Tooltip>;

export const ConversionRate = () => <Tooltip tip="The percentage of searches with `clickAnalytics` set to `true` that result in at least one conversion event." cta="Conversion rate" href="/doc/guides/search-analytics/concepts/metrics#conversion-rate">
    conversion rate (CVR)
  </Tooltip>;

Tools let agents use real data and act on real systems.
Agents equipped with tools don't rely only on their training data.
They can search catalogs, fetch live data, call external APIs, and take actions for users.

Without tools, agents can only use their training knowledge, which leads to:

* **Hallucinations**: inventing products, prices, or information that doesn't exist
* **Outdated answers**: using training data instead of current catalog information
* **Limited actions**: unable to interact with your app or external services

## Tools comparison

Agent Studio supports these tool types, each designed for different use cases:

| Tool type                                                                                             | What it does                                                                                        | Use when you need to                                                       |
| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| **[Algolia Search tool](/doc/guides/algolia-ai/agent-studio/how-to/tools/algolia-search)** (built-in) | Queries Algolia indices with natural language, a <Filter />, or keywords                            | Search your indices for products, content, or data                         |
| **[Client-side tools](/doc/guides/algolia-ai/agent-studio/how-to/tools/client-side-tools)**           | Run custom [OpenAI functions](https://platform.openai.com/docs/guides/function-calling) in your app | Access user data, trigger UI updates, or perform authenticated actions     |
| **[MCP tools](/doc/guides/algolia-ai/agent-studio/how-to/tools/mcp-tools)**                           | Connect to external services with MCP                                                               | Use Algolia MCP Server or fetch external data (weather, CRM, stock levels) |

## How tools work

When a user interacts with an AI agent, the agent analyzes the message.
It selects tools based on:

* **Tool descriptions**: clear, specific descriptions help the LLM choose the right tool
* **Agent instructions**: system prompts that guide when to use each tool
* **Conversation context**: previous messages and tool results

```mermaid theme={"system"}
sequenceDiagram
    participant User as user
    participant LLM as LLM
    participant AgentStudio as Agent Studio
    participant Tool as Tool (Search/Client/MCP)

    User->>AgentStudio: Send message
    AgentStudio->>LLM: Process with available tools
    LLM->>LLM: Decide which tools to call
    LLM->>AgentStudio: Return tool call requests
    AgentStudio->>Tool: Run tools
    Tool->>AgentStudio: Return results
    AgentStudio->>LLM: Process tool results
    LLM->>User: Generate final response
```

**By default, Agent Studio gives tools the context they need to work.**
It discovers your <Index /> data, such as facets and searchable attributes.
It also enriches tool descriptions so agents understand what's available.

At runtime, the agent decides which parameters to use based on the user's query.
These **runtime parameters** (like search queries, filters, and `hitsPerPage`) change with every request.

For more control, set **predefined parameters** when you add tools.
Use the [Agent Studio API](/doc/rest-api/agent-studio) or **Other tools** in the [Agent Studio dashboard](https://dashboard.algolia.com/generativeAi/agent-studio/agents).
These constraints apply to every tool call.
For example, you can filter out out-of-stock items or limit the retrieved attributes.

<Tabs>
  <Tab title="Runtime parameters">
    At runtime, the agent chooses parameters based on the user's query and conversation context.
    For more control, configure predefined parameters when you [add a tool](#how-tools-work).

    For the Algolia Search tool, that means the query text plus one argument per <Facet /> in your index:

    * **Search query text**: "running shoes", "laptops under \$1000"
    * **Text and boolean facets**: values the agent picks from your index metadata, which become `facetFilters`
    * **Numeric facets**: comparisons such as `<100` or `>=10`, which become `numericFilters`

    Anything else, `hitsPerPage` included, comes from the tool configuration unless you expose the field to the agent.

    ```json JSON icon=braces theme={"system"}
    {
      "type": "algolia_search_index",
      "name": "product_search",
      "indices": [
        {
          "index": "products",
          "description": "Product catalog"
        }
      ]
    }
    ```

    When a user asks "Show me running shoes under \$100", the agent decides:

    * Query: `"running shoes"`
    * `category` facet: `shoes`
    * `price` facet: `<100`

    To let the agent pick how many results to retrieve, or which attributes come back, see [Control what the AI can change per index](/doc/guides/algolia-ai/agent-studio/how-to/tools/algolia-search#control-what-the-ai-can-change-per-index).
  </Tab>

  <Tab title="Automatic enrichment">
    **For built-in Algolia tools only**:
    Agent Studio injects index metadata on its own.
    You don't need any manual setup.

    **What's automatically discovered:**

    * **Facets**: all configured facets in your index settings
    * **Searchable attributes**: attributes the LLM can mention in descriptions
    * **Analytics data**: historical query patterns (when available)

    **How automatic metadata enrichment works:**

    1. When you add an Algolia Search tool, Agent Studio calls the Algolia Search API
    2. It retrieves `attributesForFaceting`, `searchableAttributes`, and other index settings
    3. This metadata is automatically injected into the tool description sent to the LLM
    4. The LLM understands which facets exist without you manually listing them

    **Example:**

    Your configuration:

    ```json JSON icon=braces theme={"system"}
    {
      "index": "products",
      "description": "Ecommerce product catalog"
    }
    ```

    What the LLM receives:

    ```txt theme={"system"}
    Ecommerce product catalog

    Available facets: brand, category, color, size, price_range
    Searchable attributes: title, description, brand
    ```

    **Benefits:**

    * Manual facet configuration isn't needed
    * Automatically stays in sync with index changes
    * Reduces configuration errors
    * Improves tool call accuracy
  </Tab>

  <Tab title="Predefined parameters">
    Predefined parameters are constraints you set at configuration time that apply to every tool call.
    Use them to enforce constraints, limit retrieved data, or apply consistent filters.

    **When to use predefined parameters:**

    * Always filter out out-of-stock items
    * Limit retrieved attributes to reduce token costs
    * Apply consistent ranking or relevance rules
    * Configure faceting behavior

    **Configuration methods:**

    * **[Agent Studio API](/doc/rest-api/agent-studio)**: full control over all parameters
    * **[Other tools](https://dashboard.algolia.com/generativeAi/agent-studio/agents)** option in the Algolia dashboard: JSON configuration for advanced settings

    For example:

    <AccordionGroup>
      <Accordion title="Always filter out-of-stock items">
        ```json JSON icon=braces theme={"system"}
        {
          "type": "algolia_search_index",
          "name": "product_search",
          "indices": [
            {
              "index": "products",
              "description": "Product catalog",
              "searchParameters": {
                "filters": "inStock:true",
                "attributesToRetrieve": ["title", "price", "image"]
              }
            }
          ]
        }
        ```

        In this example:

        * **Predefined**: `filters: "inStock:true"` (always applied), `attributesToRetrieve` (limits fields)
        * **Runtime**: query text, facet filters, hitsPerPage (decided by agent)
      </Accordion>

      <Accordion title="Facet discovery without retrieving hits">
        ```json JSON icon=braces theme={"system"}
        {
          "type": "algolia_search_index",
          "name": "product_search",
          "indices": [
            {
              "index": "products",
              "description": "Product catalog",
              "searchParameters": {
                "facets": ["*"],
                "maxValuesPerFacet": 100,
                "hitsPerPage": 0
              }
            }
          ]
        }
        ```

        <Note>
          Set `hitsPerPage: 0` and `facets: ["*"]`.
          The agent then receives all facet values, such as `brand: ["Nike", "Adidas", "Puma"]` and `color: ["red", "blue", "black"]`, without retrieving any products.
          This provides the agent with all valid filter options. It improves accuracy for questions like "Which categories have the most products?" or "What colors are available?"
        </Note>

        **Common predefined parameters:**

        * `filters`: always-applied filter conditions
        * `attributesToRetrieve`: limit returned fields
        * `facets`: which facets to expose
        * `maxValuesPerFacet`: limit facet value counts
        * `hitsPerPage`: set to `0` for facet-only queries
        * `enableRules`: turn query rules on or off
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

These concepts help you build reliable, efficient tools for agents.

## Business value unlocked by tools

<Accordion title="Real-time data access">
  **Problem**: agents using only training data provide outdated or invented information.

  **Solution**: Algolia Search tool queries your live index, ensuring accurate, current responses.

  **Example**: "What Christian Siriano cases do you have?" searches your actual product catalog instead of guessing.

  **Business impact**:

  * Reduce hallucinations and incorrect product information
  * Always reflect current inventory and pricing
  * Build user trust with accurate, grounded responses
</Accordion>

<Accordion title="Personalized experiences">
  **Problem**: generic responses that don't account for user context.

  **Solution**: client-side tools access user-specific data like shopping cart contents, order history, and preferences.

  **Example**: "What's in my cart?" retrieves the actual user's cart, not a generic response.

  **Business impact**:

  * Increases <ConversionRate /> with personalised recommendations
  * Reduce support costs with context-aware responses
  * Improve customer satisfaction through relevant interactions
</Accordion>

<Accordion title="Extended capabilities">
  **Problem**: agents can't interact with external systems or third-party data.

  **Solution**: MCP tools connect to weather APIs, inventory systems, CRMs, and more.

  **Example**: "What gear should I bring for hiking in Seattle this weekend?" uses a weather API to suggest the right outdoor gear from your catalog.

  **Business impact**:

  * Unlock new use cases by combining multiple data sources
  * Provide context-aware recommendations based on external factors
  * Create differentiated experiences competitors can't replicate
</Accordion>

<Accordion title="Actionable agents">
  **Problem**: agents can only provide information, not take action.

  **Solution**: client-side tools carry out actions like adding items to a shopping cart or applying filters.

  **Example**: "Add this laptop to my cart" adds the product, rather than just confirming it's possible.

  **Business impact**:

  * Reduce friction in the purchase journey
  * Increase conversion with seamless cart management
  * Enable automated shopping experiences
</Accordion>

<Accordion title="Parallel tool calling">
  **Problem**: sequential tool calls create delays and consume more tokens through multiple inference rounds.

  **Solution**: Agent Studio supports parallel tool calling.
  The LLM can call multiple tools at once and process all results in a single inference step.

  **Example**: "Compare prices for running shoes across our outlet and premium stores" calls both indices at once, instead of one after the other.
  The two searches require one round trip instead of two.

  **Business impact**:

  * Reduce response latency for complex queries requiring multiple data sources
  * Lower token consumption and LLM costs by eliminating repeated tool calls (agentic loops)
  * Improve user experience with faster, more efficient responses

  <Note>
    This capability depends on the selected LLM model but most support it by default.
  </Note>
</Accordion>

## Test tools in live preview

After configuring tools, check they work using the **Live preview** panel in the [Agent Studio dashboard](/doc/guides/algolia-ai/agent-studio/how-to/dashboard#test-your-agent).
Send a test message that should trigger a tool call.

When the agent calls a tool, you'll see an expandable tool indicator in the conversation.
It shows:

* **Tool used**: the tool the agent used (for example, `algolia_search_index`)
* **Arguments**: the parameters the agent sent (index name, query, filters, limits)
* **Result**: the data the tool returned (search hits, product details, API responses)

Click the tool indicator to expand and inspect the full request and response details.

<img src="https://mintcdn.com/algolia/n_gdBwT_QFZcudWB/doc/guides/algolia-ai/agent-studio/how-to/tools/agent-studio-tool-call-debug.png?fit=max&auto=format&n=n_gdBwT_QFZcudWB&q=85&s=e33ae77e7acbf14e09552ad365bccb90" alt="Screenshot of a tool call debugging interface showing a search query for 'smartwatch' with arguments and results displayed in a code block." width="2038" height="1492" data-path="doc/guides/algolia-ai/agent-studio/how-to/tools/agent-studio-tool-call-debug.png" />

### Debug your tools

* **Tool not called**: verify tool descriptions and agent instructions are clear and specific
* **Incorrect parameters**: check tool parameter definitions, descriptions, and required field constraints
* **Unexpected response format**: test tool implementation and ensure data structure matches schema
* **Agent misinterprets results**: refine tool descriptions or add examples in agent instructions
* **Tool timeout or error**: review server logs, authentication credentials, and network connectivity

## Optimize tool usage

* **Start simple**: begin with one Algolia Search tool. Test it, then add complexity only when needed. Using more than 10 tools can reduce agent reliability.
* **Write clear descriptions**: use specific descriptions, such as "Ecommerce product catalog with electronics, clothing, and home goods." Avoid generic ones like "Products." Clear descriptions help the agent decide well.
* **Limit tool count**: aim for 3-5 tools per agent. More than 10-15 tools can reduce accuracy as each tool increases cognitive load.
* **Test incrementally**: add one tool at a time and verify it works before adding more. This isolates issues and prevents compounding complexity.

## See also

* [Algolia Search tool](/doc/guides/algolia-ai/agent-studio/how-to/tools/algolia-search)
* [Client-side tools](/doc/guides/algolia-ai/agent-studio/how-to/tools/client-side-tools)
* [MCP tools](/doc/guides/algolia-ai/agent-studio/how-to/tools/mcp-tools)
* [Security and credentials](/doc/guides/algolia-ai/agent-studio/how-to/tools/security)