Dashboard/Algolia-Central/Knowledge/AgentStudio/02-tool-types.md
Algolia-Central

Knowledge/AgentStudio/02-tool-types.md

02 — Tool Types

Agent Studio supports six tool types via the tools array's discriminated union on the type field (per 05-api-reference.md §7 "Tool Types").

The six types

Type Identifier Execution Purpose
Algolia Search algolia_search_index Server-side (Algolia) Query 1-10 Algolia indices with natural language, keywords, or filters
Algolia Recommend algolia_recommend Server-side (Algolia) Personalized recommendations: trending, related, bought-together
Algolia Display Results algolia_display_results Server-side (Algolia) Controls how search/recommend results render to the user
Client-side client_side (also function) App / frontend Custom OpenAI Function Calling — runs in YOUR app, results return to agent
MCP mcp_tools External MCP server Connect to external services via Model Context Protocol
Unknown unknown — Future-proofing fallback for unrecognized tool types

Type 1: algolia_search_index

The most-used tool type. Production agents almost always have at least one.

Capabilities

  • Natural language queries, keyword search, faceted filtering with AND/OR logic
  • Up to 10 indices per agent, queried in parallel or sequentially
  • Automatic metadata enrichment — Agent Studio reads index settings and injects attributesForFaceting, searchableAttributes, custom ranking into the LLM-visible tool description automatically. This is the enhancedDescription field. The LLM sees what facets and values are valid before it queries. (Source: 02-tools.md §1.3.)
  • Full Search API parameter support
  • Analytics auto-tagged with alg#agent-studio
  • Runtime parameter overrides via algolia.searchParameters in completions request

Schema

{
  "type": "algolia_search_index",
  "name": "product_search",
  "indices": [
    {
      "index": "products",
      "description": "Product catalog with electronics, clothing, and home goods",
      "searchParameters": {
        "filters": "isPublished:true AND inStock:true",
        "attributesToRetrieve": ["title", "price", "image", "brand"],
        "attributesToHighlight": ["title", "description"],
        "hitsPerPage": 20,
        "analytics": true,
        "clickAnalytics": true
      }
    }
  ],
  "predefinedSearchParameters": {
    "analytics": true
  }
}

Two parameter levels

  • Per-index searchParameters — applies to a specific index. Most common.
  • Global predefinedSearchParameters — applies across all indices in this tool.

Tool config takes precedence over runtime overrides.

Per-index runtime overrides (allowed fields, per 02-tools.md §2.6)

filters, attributesToRetrieve, restrictSearchableAttributes, distinct, userToken, enablePersonalization, personalizationImpact.

Security

  • Use Search API keys, never Admin API keys.
  • Supports secured API keys for row-level access control (filter restrictions baked into the key).
  • Credentials encrypted at rest in Agent Studio's database.

When to use

Almost always, in some form. The exception is pure-text agents (classifiers, query rewriters) where the agent shouldn't search at all.

Type 2: algolia_recommend

Algolia Recommend integration. Models supported: related-products, bought-together, frequently-bought-together, trending-items, looking-similar. Production usage in shopping assistants is via the bundle_suggestion and trending_items client-side wrappers, not direct config.

We have not used this directly. May be relevant for "related content" / "trending content" patterns in Algolia Central.

Type 3: algolia_display_results

A built-in tool we hadn't noticed in earlier analysis. Per 02-tools.md §1.1, it controls how search/recommend results render to the user. Limited published documentation. The shopping assistants tend to use a custom client_side show_products tool instead, which suggests algolia_display_results is either newer or less customizable than building your own.

Status: under-documented. Treat as known-but-not-yet-used.

Type 4: client_side (the most consequential type for our refactor)

Architecture & lifecycle (per 02-tools.md §3.2)

This is NOT fire-and-forget. It is round-trip:

  1. End user sends message to agent
  2. Agent determines a client-side tool is needed
  3. Agent returns a tool call request to the application (structured JSON matching the tool's input schema)
  4. Application runs the tool locally (NOT Agent Studio)
  5. Application sends tool result back via addToolResult({ output: { ... } })
  6. Agent processes the result and continues responding

This means tool RESULT design matters as much as tool INPUT design. The agent uses the tool's output to inform its next message.

Two-location setup

  • Agent Studio — tool schema (JSON, with inputSchema)
  • Frontend or backend code — implementation that handles onToolCall and calls addToolResult

Schema (OpenAI Function Calling spec)

{
  "type": "function",
  "function": {
    "name": "get_user_cart",
    "description": "Retrieves the user's shopping cart",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {},
      "required": [],
      "additionalProperties": false
    }
  }
}

Note: in many demo agents the type is "client_side" directly with inputSchema and description at the top level (without the function wrapper). Both forms appear in production.

  • All properties must be in required array
  • Optional fields use ["type", "null"] syntax
  • Set additionalProperties: false
  • Use enum for restricted values
  • Set minimum/maximum for numbers

Tool name constraints

  • 3-64 characters, alphanumeric + underscores only

Frontend implementation

React InstantSearch native:

<Chat
  agentId={agentId}
  tools={{
    get_user_cart: {
      onToolCall: async ({ addToolResult }) => {
        const cart = await getUserCart(currentUserId);
        addToolResult({ output: { items: cart.items, total: cart.total } });
      }
    }
  }}
/>

Key integration rules: - Tool prop keys must match Agent Studio tool names exactly - onToolCall receives { input, addToolResult, ...slots } - addToolResult returns the output to the agent (may be string or object) - Each tool can have an associated layoutComponent that renders the tool's call/result as a UI element

See 08-frontend-integration for full Chat widget integration.

Use cases

  • User context access (cart, preferences, order history, auth tokens) — these can't be fetched server-side because they require user auth context
  • Action execution (add to cart, apply filters, update profile)
  • UI updates (refine search, show product cards, render comparison tables)
  • Anything that runs in the user's security context

Security model

  • Agent Studio stores no credentials for client-side tools.
  • App manages authentication in user's security context.
  • Auth tokens NEVER transmitted to Agent Studio.

Type 5: mcp_tools

External services via Model Context Protocol.

Schema

{
  "type": "mcp_tools",
  "name": "weather_api",
  "url": "https://weather-api.example.com/mcp",
  "transport": "streamable_http",
  "headers": {
    "Authorization": "Bearer EXTERNAL_API_KEY"
  },
  "allowedTools": {
    "get_forecast": { "alias": "check_weather" },
    "get_alerts": true,
    "admin_endpoint": false
  }
}

Constraints (per 02-tools.md §4)

  • Transport MUST be "streamable_http". STDIO and SSE are NOT supported.
  • 10-second connection timeout
  • Max 10 headers per server
  • allowedTools filters: true (enable), false (block), { alias: "new_name" } (rename), { requiresApproval: true } (gate behind two-request approval flow)

Approval flow (requiresApproval: true)

Two-request pattern (per 02-tools.md §4.8): 1. Request 1: user sends message → agent returns finishReason: "tool-approval-required" with approval-request part 2. Request 2: client submits toolApprovals: { "{toolCallId}": { approved: true|false, timestamp: "ISO8601" } } → tool executes (or rejects), agent continues

Reserve for sensitive operations: destructive actions, sensitive data access, system config changes. Adds latency.

When to use

  • Connecting to external APIs (CRM, weather, inventory, payment)
  • Calling another Algolia agent's /completions endpoint as a tool (technically possible — see 06-multi-index-routing for why this is generally NOT what you want)
  • Algolia MCP Server (separate product) for read-only access to Algolia data from external agents

Type 6: unknown

Future-proofing. Schema returned by API for tools the platform recognizes but the SDK version doesn't. Don't author these intentionally.

Tool count guidelines (per 02-tools.md §1.7)

  • Start with one Algolia Search tool before adding complexity.
  • 3-5 tools per agent maximum is the official recommendation.
  • Avoid more than 10-15.
  • Production shopping assistants exceed this (11-13 tools) and work, but they're heavily prompt-tuned. Not the default best practice.
  • Write specific descriptions ("electronics, clothing, home goods") not generic ones ("products").
  • Add tools incrementally and test each before proceeding.

Implication for us: Elena and Bruno today have 1 tool each. We have headroom to add 2-4 client-side tools each before we hit the official ceiling.

Parallel tool calling

The LLM can invoke multiple tools simultaneously in a single inference step. Per 02-tools.md §1.6: "halving response time and token usage" for complex queries. Most relevant for multi-tool agents (shopping assistants); less relevant for our 1-2 tool agents.

Tool selection by the LLM

The LLM picks tools based on description (and enhancedDescription for search tools). This means tool descriptions are PROMPTS — they're how you teach the LLM when to invoke each tool. Bad description = wrong tool selected.

Pattern from production agents: - Lead with WHAT the tool does ("Discover products by suggesting relevant searches") - Specify WHEN to use it ("Use when user wants to explore new products") - Specify WHEN NOT to use it where overlap exists ("Do not use for refining visible results") - For search tools, the index description should describe the data, not the usage ("Product catalog with electronics" beats "Use this index when you need products")

Anti-patterns we see in our agents

  1. Tools doing what config can do. If you wrap memory/suggestions/conversation persistence in custom code instead of using the config.memory.enabled and config.suggestions.enabled flags, you're fighting the platform.
  2. Text output where structured tools belong. Elena's <specialist_summary> / <implementation_steps> / <operational_gotchas> XML sections are exactly the shape of client_side tools with layoutComponent. We force the agent to emit a 2,000-word XML document, then parse it with a 350-line stream adapter, when one round-trip tool call would do the same job natively.
  3. Single tool with too many indices. Not yet our problem (we have 2 indices), but watch for it as we expand. The 10-index ceiling is hard.

What this section does NOT cover